{
  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
  "name": "pinned-scene",
  "title": "Pinned Scene",
  "author": "Visant Labs <visantsupply@gmail.com>",
  "description": "A dobra que prende a arte e avança em passos. O pin é position:sticky, não ScrollTrigger.pin — o GSAP entra só pra relatar progresso em --p, --sp e --near, sem tocar no DOM.",
  "dependencies": [
    "gsap"
  ],
  "registryDependencies": [
    "utils"
  ],
  "files": [
    {
      "path": "registry/visant/ui/pinned-scene.tsx",
      "content": "\"use client\";\n\nimport * as React from \"react\";\nimport gsap from \"gsap\";\nimport { ScrollTrigger } from \"gsap/ScrollTrigger\";\n\nimport { cn } from \"@/lib/utils\";\n\ngsap.registerPlugin(ScrollTrigger);\n\n/**\n * Pinned Scene — a dobra que prende e avança em passos.\n *\n * O registry tinha `timeline` (progresso amarrado ao scroll, mas em fluxo\n * normal) e `rail` (trilho horizontal, dirigido pela mão). Faltava a peça que\n * segura a arte parada enquanto o texto passa — o gesto de \"como funciona\", de\n * tour de produto, de método em quatro etapas.\n *\n * ── A decisão que economiza o dia inteiro: o pin é `sticky`, não é GSAP ────\n *\n * `ScrollTrigger.pin` funciona, e cobra caro: ele injeta um wrapper no DOM,\n * troca o elemento pra `position: fixed` e reserva o espaço com um spacer\n * calculado. Isso quebra em três lugares que sempre aparecem em site de\n * cliente — dentro de container com `overflow` ou `transform`, com scroll\n * suave (Lenis) em cima, e em qualquer coisa que mude de altura depois do\n * `refresh()` (fonte da marca carregando, imagem sem `width`/`height`,\n * acordeão abrindo). `position: sticky` é o navegador fazendo o mesmo trabalho\n * sem tocar no DOM, e ele nunca precisa de `refresh`.\n *\n * Então aqui o ScrollTrigger faz só o que sticky não sabe fazer: **relatar\n * progresso**. Ele escreve `--p` (a cena inteira), `--sp` (o passo) e `--near`\n * (1 no meio do passo, 0 nas pontas) e não move nada. Quem move é o CSS.\n *\n * ── Por que a arte NÃO é uma pilha de camadas em cross-fade ───────────────\n *\n * A versão com todas as artes empilhadas em `absolute` e trocadas por opacidade\n * parece mais sofisticada e é pior: a arte deixa de ter posição no documento,\n * o leitor de tela recebe cinco imagens de uma vez, e cada passo precisa de\n * `inert` pra não virar armadilha de foco. Aqui cada passo é um `<article>` de\n * verdade com a arte DELE, grudada dentro da própria linha. A troca acontece\n * porque a linha acabou — é o navegador, não é animação. Resultado: sem JS,\n * sem `prefers-reduced-motion`, com `Ctrl+F` e com leitor de tela, a cena\n * continua sendo uma sequência legível de passos.\n *\n * ── O caminho sem movimento ───────────────────────────────────────────────\n *\n * Sob `prefers-reduced-motion` o GSAP nem inicializa. Os `var(--near, 1)` têm\n * default 1, então a arte fica em opacidade e escala plenas — o repouso correto,\n * não um estado quebrado. No mobile a grade vira uma coluna e o sticky continua\n * valendo, com a arte acima do texto do passo.\n *\n * ── Um limite que vale conhecer antes de descobrir na unha ────────────────\n *\n * O ScrollTrigger mede por `getBoundingClientRect`, e rect é geometria PINTADA:\n * qualquer ancestral com `transform: scale()` entrega medidas encolhidas\n * enquanto o `scrollTop` continua em pixel real. Os dois não conversam, e o\n * resultado é uma faixa de rolagem de tamanho zero — sem erro no console.\n * Aconteceu na própria vitrine da casa, cujo palco escala a demo pra caber no\n * card. Em página de cliente isso não existe; dentro de palco escalado, o `pin`\n * por `sticky` continua funcionando (é layout, não rect) e só o progresso\n * (`--p`, `--near`, a régua) fica parado. Por isso a régua sai da demo do\n * catálogo, e não porque a peça esteja quebrada.\n *\n * Requer `gsap` no projeto.\n */\n\nexport interface PinnedStep {\n  id: string;\n  /** Rótulo curto do passo. É o que a régua mostra — 1–2 palavras. */\n  label?: React.ReactNode;\n  title: React.ReactNode;\n  body?: React.ReactNode;\n  /** Slot da arte: `next/image`, vídeo, um `@visant/cover-art`, um canvas. */\n  art?: React.ReactNode;\n}\n\nexport interface PinnedSceneProps extends React.HTMLAttributes<HTMLElement> {\n  steps: PinnedStep[];\n  /** De que lado a arte gruda. `left` é o padrão de leitura ocidental. */\n  side?: \"left\" | \"right\";\n  /** Distância do topo em que a arte trava. Deixe espaço pro header fixo. */\n  top?: string;\n  /**\n   * Altura de cada passo — é o que define o comprimento de rolagem da cena.\n   * `100svh` é o padrão (e `svh`, não `vh`: no iOS o `vh` conta a barra de\n   * endereço que já recolheu, e cada passo ganharia uns 70px de vão morto).\n   * Baixar pra `70svh` deixa a cena mais rápida; abaixo disso a arte troca antes\n   * de a pessoa terminar de ler.\n   */\n  stepHeight?: string;\n  /** Régua de progresso com contagem. Some abaixo de `md`. */\n  rail?: boolean;\n  /**\n   * Avisa quando o passo ativo muda. Serve pra trocar um vídeo, disparar\n   * analytics de dobra, ou acender algo fora da peça. Recebe o índice e o passo.\n   */\n  onStepChange?: (index: number, step: PinnedStep) => void;\n  /**\n   * Quem rola, quando não é a janela: um `overflow-y: auto` (documentação,\n   * modal, painel). O `sticky` já funciona dentro de container sem ajuda; isto\n   * existe só pra o ScrollTrigger medir o progresso no mesmo scroller, senão a\n   * régua fica parada enquanto a cena anda.\n   */\n  scroller?: string | HTMLElement | null;\n}\n\nconst useIsomorphicLayoutEffect =\n  typeof window !== \"undefined\" ? React.useLayoutEffect : React.useEffect;\n\nexport function PinnedScene({\n  steps,\n  side = \"left\",\n  top = \"12vh\",\n  stepHeight = \"100svh\",\n  rail = true,\n  onStepChange,\n  scroller = null,\n  className,\n  style,\n  ...props\n}: PinnedSceneProps) {\n  const rootRef = React.useRef<HTMLElement>(null);\n  const [active, setActive] = React.useState(0);\n\n  // O callback entra por ref, e não nas dependências do efeito: passado como\n  // arrow inline (que é como todo mundo passa), ele muda de identidade a cada\n  // render e derrubaria e recriaria os ScrollTriggers da cena inteira em cada\n  // troca de passo — que é justamente quando ele dispara.\n  const aviso = React.useRef(onStepChange);\n  React.useEffect(() => {\n    aviso.current = onStepChange;\n  }, [onStepChange]);\n\n  React.useEffect(() => {\n    aviso.current?.(active, steps[active]);\n    // `steps` fora das dependências de propósito: quem manda aqui é a troca de\n    // passo, e a lista costuma ser um literal remontado a cada render.\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [active]);\n\n  useIsomorphicLayoutEffect(() => {\n    const root = rootRef.current;\n    if (!root) return;\n\n    const mm = gsap.matchMedia();\n\n    mm.add(\"(prefers-reduced-motion: no-preference)\", () => {\n      // `setProperty` na unha, e não `gsap.quickSetter(root, \"--p\")`: o\n      // quickSetter escreve em `el.style[prop]`, e propriedade customizada só\n      // entra por `setProperty`. Ele não reclama — só não escreve nada, e a\n      // régua fica parada com a cena andando.\n      const setP = (v: string) => root.style.setProperty(\"--p\", v);\n      const common = scroller ? { scroller } : {};\n\n      // A cena inteira: `--p` de 0 a 1 do topo do primeiro passo ao fim do\n      // último. É o número que a régua consome, e o que o consumidor pode usar\n      // pra girar, colorir ou contar qualquer coisa por fora da peça.\n      const scene = ScrollTrigger.create({\n        ...common,\n        trigger: root,\n        start: \"top top\",\n        end: \"bottom bottom\",\n        onUpdate: (self) => {\n          setP(String(self.progress));\n          // O passo ativo sai do MESMO número, e não de um gatilho por passo.\n          // A primeira versão criava um ScrollTrigger `top center`/`bottom\n          // center` por passo e lia `isActive`: na montagem os três se\n          // anunciavam ativos na ordem, e a régua abria em \"03 / 03\" com a cena\n          // parada no começo. Com `end: bottom bottom` o percurso vai de 0 no\n          // primeiro passo a 1 no último, então arredondar é exato — e é uma\n          // fonte de verdade só, que nunca discorda da barra.\n          setActive(Math.round(self.progress * (steps.length - 1)));\n        },\n      });\n\n      const perStep = gsap.utils.toArray<HTMLElement>(\"[data-pinned-step]\", root).map((el) =>\n        ScrollTrigger.create({\n          ...common,\n          trigger: el,\n          start: \"top bottom\",\n          end: \"bottom top\",\n          onUpdate: (self) => {\n            el.style.setProperty(\"--sp\", String(self.progress));\n            // Triângulo: 0 nas pontas, 1 no meio da travessia. Feito aqui e não\n            // em CSS porque `abs()` ainda não é seguro em navegador de cliente.\n            el.style.setProperty(\"--near\", String(1 - Math.abs(self.progress * 2 - 1)));\n          },\n        }),\n      );\n\n      /*\n       * O gatilho mede a cena no instante em que nasce, e nesse instante ela\n       * quase nunca tem a altura final: a foto ainda não baixou, a fonte da\n       * marca ainda não trocou pela real, o modal ainda está entrando. Medido\n       * aqui: `start` e `end` saíam ambos 0 — faixa de rolagem zero — e nada\n       * jamais atualizava, sem erro nenhum no console.\n       *\n       * O `ResizeObserver` no root resolve os três casos de uma vez, porque\n       * todos terminam em \"a altura mudou\". O rAF junta a rajada de mudanças\n       * numa medida só; sem ele, uma imagem por passo vira uma remedida por\n       * passo, cada uma percorrendo todos os gatilhos da página.\n       */\n      let pending = 0;\n      const ro = new ResizeObserver(() => {\n        cancelAnimationFrame(pending);\n        pending = requestAnimationFrame(() => {\n          // Remede só os gatilhos DESTA cena, e não `ScrollTrigger.refresh()`\n          // global: o global recalcula tudo que existe na página, inclusive o\n          // pin de outro componente que não mudou de tamanho nenhum. Quem\n          // cresceu foi este root — o `ResizeObserver` observa ele e mais nada.\n          scene.refresh();\n          perStep.forEach((t) => t.refresh());\n        });\n      });\n      ro.observe(root);\n\n      return () => {\n        cancelAnimationFrame(pending);\n        ro.disconnect();\n        scene.kill();\n        perStep.forEach((t) => t.kill());\n      };\n    });\n\n    return () => mm.revert();\n  }, [steps.length, scroller]);\n\n  return (\n    <section\n      ref={rootRef}\n      className={cn(\"pinned-scene relative\", className)}\n      style={\n        { \"--pinned-top\": top, \"--pinned-h\": stepHeight, ...style } as React.CSSProperties\n      }\n      {...props}\n    >\n      {rail && (\n        // `h-0` + `sticky`: a régua gruda sem ocupar altura nenhuma no fluxo —\n        // um wrapper com altura empurraria o primeiro passo pra baixo em uma\n        // tela inteira. O conteúdo dela transborda de propósito.\n        <div\n          aria-hidden=\"true\"\n          className=\"pointer-events-none sticky top-[var(--pinned-top)] z-10 hidden h-0 md:block\"\n        >\n          <div\n            className={cn(\n              \"absolute flex flex-col gap-3\",\n              side === \"left\" ? \"right-0 items-end\" : \"left-0 items-start\",\n            )}\n          >\n            <span className=\"text-[length:var(--text-rotulo,0.6875rem)] tabular-nums tracking-[0.14em] text-muted-foreground\">\n              {String(active + 1).padStart(2, \"0\")}\n              <span className=\"opacity-40\"> / {String(steps.length).padStart(2, \"0\")}</span>\n            </span>\n            <span className=\"relative block h-24 w-px bg-border\">\n              {/* A barra é `scaleY` sobre `--p`: uma altura em % obrigaria\n                  layout a cada frame, e isto aqui roda no compositor. */}\n              <span\n                className=\"absolute inset-0 block origin-top bg-[var(--brand,var(--foreground))]\"\n                style={{ transform: \"scaleY(var(--p, 0))\" }}\n              />\n            </span>\n          </div>\n        </div>\n      )}\n\n      {steps.map((step, i) => (\n        <article\n          key={step.id}\n          data-pinned-step=\"\"\n          data-active={i === active || undefined}\n          className=\"pinned-step grid items-start gap-x-12 gap-y-6 md:grid-cols-2 lg:gap-x-20\"\n        >\n          <div\n            className={cn(\n              // A arte gruda dentro da PRÓPRIA linha: quando o passo acaba, ela\n              // sai empurrada pelo próximo. É a troca sem cross-fade da nota.\n              \"pinned-art md:sticky md:top-[var(--pinned-top)]\",\n              \"h-[calc(var(--pinned-h)*0.45)] md:h-[calc(var(--pinned-h)*0.7)]\",\n              side === \"right\" && \"md:order-2\",\n            )}\n            style={{\n              opacity: \"calc(0.5 + 0.5 * var(--near, 1))\",\n              transform: \"scale(calc(0.975 + 0.025 * var(--near, 1)))\",\n              transition: \"opacity 120ms linear\",\n            }}\n          >\n            <div className=\"h-full w-full overflow-hidden rounded-[var(--r-surface,0.875rem)] bg-muted\">\n              {step.art}\n            </div>\n          </div>\n\n          {/* É a coluna de texto que dá comprimento de rolagem ao passo — ver\n              `stepHeight`. No mobile ela encolhe: com a arte empilhada em cima,\n              a altura cheia deixaria meia tela vazia entre as duas. */}\n          <div className=\"flex min-h-[calc(var(--pinned-h)*0.7)] flex-col justify-center py-10 md:min-h-[var(--pinned-h)]\">\n            {step.label && (\n              <div className=\"mb-3 flex items-center gap-3 text-[length:var(--text-rotulo,0.6875rem)] uppercase tracking-[0.14em] text-muted-foreground\">\n                <span className=\"tabular-nums\">{String(i + 1).padStart(2, \"0\")}</span>\n                <span className=\"h-px w-6 bg-border\" />\n                {step.label}\n              </div>\n            )}\n            <h3 className=\"text-balance text-[length:var(--text-titulo,1.75rem)] font-semibold tracking-[-0.02em] text-foreground\">\n              {step.title}\n            </h3>\n            {step.body && (\n              <div className=\"mt-4 max-w-[46ch] text-pretty text-[length:var(--text-corpo,0.9375rem)] leading-relaxed text-muted-foreground\">\n                {step.body}\n              </div>\n            )}\n          </div>\n        </article>\n      ))}\n    </section>\n  );\n}\n",
      "type": "registry:ui"
    }
  ],
  "meta": {
    "uso": {
      "quando": "Dobra de storytelling que prende a arte e avança em passos enquanto o texto rola",
      "evite": "Passos sem prender a tela: step-cards; caminhada 3D na névoa, fog-garden"
    }
  },
  "categories": [
    "conteudo",
    "scroll",
    "sticky",
    "passos",
    "storytelling",
    "gsap"
  ],
  "type": "registry:ui"
}