@sumi-forge/react 0.0.0-stage → 1.0.1

package/LICENSE.md

@@ -0,0 +1,29 @@
+# Apache License 2.0
+
+Copyright (c) 2025-2026 SumiForge (`@sumi-forge/react`) Contributors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at:
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+---
+
+## Resumo de Permissões (Português)
+
+Você é livre para usar o **`@sumi-forge/react`** em projetos pessoais, acadêmicos ou comerciais, desde que mantenha os avisos de direitos autorais e a licença original.
+
+- **Uso Comercial Permitido**: Utilize em landing pages, produtos SaaS, jogos web e portfólios.
+- **Modificação e Distribuição**: Crie novos pincéis, paletas e coreografias de revelação.
+- **Uso de Patentes e Contribuições**: Protegido pelos termos da Apache License 2.0.
+
+---
+
+*made with love in Japa.... ops, Brazil*

package/README.md

@@ -1,3 +1,291 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# 墨 SumiForge · `@sumi-forge/react`
+
+**Onde a Web deixa de ser código e vira pintura viva.**  
+*Biblioteca React de arte japonesa procedural, revelação de imagens a pincel, sensibilidade à pressão no toque/mouse e cenários vivos em papel Washi.*
+
+[![npm version](https://img.shields.io/badge/npm-@sumi--forge%2Freact%20v1.4.0-C8232C?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/)
+[![React](https://img.shields.io/badge/React-18%20%7C%2019-11100E?style=for-the-badge&logo=react&logoColor=61DAFB)](https://react.dev/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.8%20Strict-11100E?style=for-the-badge&logo=typescript&logoColor=3178C6)](https://www.typescriptlang.org/)
+[![Performance](https://img.shields.io/badge/Render-60%20%2F%20120%20FPS%20Offscreen%20Cache-C8232C?style=for-the-badge)](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API)
+[![Mobile Touch](https://img.shields.io/badge/Mobile%20Touch-Pintura%20%26%20Revela%C3%A7%C3%A3o%20T%C3%A1til-11100E?style=for-the-badge)](#pintura-e-revelacao-no-mobile)
+[![License](https://img.shields.io/badge/License-Apache%202.0-D5CEC0?style=for-the-badge&labelColor=11100E)](./LICENSE.md)
+[![PRs Welcome](https://img.shields.io/badge/PRs-Bem--vindos-C8232C?style=for-the-badge)](./CONTRIBUTING.md)
+
+<br />
+
+<img src="./public/og-sumi-forge.png" alt="SumiForge — Pintura Viva do Monte Fuji, Sakura e Sol Carmesim em Papel Washi" width="100%" />
+
+<br />
+
+[**Explorar Obra Viva**](#visao-geral) · [**Instalação**](#instalacao) · [**Componentes React**](#componentes-principais) · [**Pintura no Mobile**](#pintura-e-revelacao-no-mobile) · [**Como Contribuir**](./CONTRIBUTING.md)
+
+</div>
+
+---
+
+## 一期一会 · Visão Geral (`Ichigo Ichie`)
+
+> *"Cada encontro e cada pincelada são únicos na vida."*
+
+**`@sumi-forge/react`** transforma aplicações React em pergaminhos vivos inspirados na arte japonesa tradicional (**Sumi-e**, **Suibokuga**, **Tarashikomi** e **Ukiyo-e**). Sem depender de vídeos pesados ou arquivos estáticos repetitivos, cada montanha, flor de cerejeira, rio de carpas e golpe de pincel nasce em tempo real na tela e adapta-se com nitidez absoluta a celulares, tablets e monitores ultrawide.
+
+### Por que usar o `@sumi-forge/react`?
+
+- **Cerimônia de Abertura em 3 Atos**: O Sol Carmesim surge como mancha de aquarela úmida (*Tarashikomi*), os traços de nanquim revelam o Monte Fuji e os galhos da cerejeira, e as flores de Sakura desabrocham como manchas vivas sobre a madeira.
+- **Revelação Artística de Imagens (`<SumiMaskReveal />`)**: Revele qualquer fotografia ou arte com golpes de pincel animados ou deixe que o próprio visitante revele a imagem passando o dedo na tela do celular.
+- **Atelier com Pressão e Velocidade (`<SumiBrushCanvas />`)**: Suporte nativo a telas sensíveis ao toque (iOS/Android), Apple Pencil, Wacom e mouse. Movimentos lentos depositam nanquim denso; movimentos rápidos abrem as cerdas secas (*Kasure*) ou fazem brotar flores de Sakura.
+- **Performance Extrema (60/120 FPS)**: Arquitetura com cache offscreen inteligente e pausa automática fora da tela (`IntersectionObserver`), garantindo rolagem fluida mesmo em smartphones intermediários.
+- **UI Desenhada à Mão (`<SumiButton />` & `<SumiIcon />`)**: Botões com bordas retas orgânicas e ícones caligráficos vetoriais gerados proceduralmente.
+
+---
+
+## Instalação
+
+Instale o pacote com seu gerenciador favorito:
+
+```bash
+# Usando npm
+npm install @sumi-forge/react
+
+# Usando pnpm
+pnpm add @sumi-forge/react
+
+# Usando yarn
+yarn add @sumi-forge/react
+```
+
+---
+
+## Componentes Principais
+
+### 1. `<SumiMaskReveal />` · Revelação de Imagens a Pincel & Toque
+
+Envolva qualquer imagem para que ela seja pintada ao vivo na tela ou revelada pelo dedo do usuário no celular.
+
+```tsx
+import { SumiMaskReveal } from '@sumi-forge/react';
+
+export function ProductHeroArtwork() {
+  return (
+    <div className="w-full h-[420px] rounded-2xl overflow-hidden">
+      <SumiMaskReveal
+        src="/assets/minha-obra.png"
+        choreography="fuji_masterpiece" // 'fuji_masterpiece' | 'katana_slashes' | 'hokusai_tide' | 'enso_spiral' | 'interactive_brush'
+        duration={3.2}
+        bristleCount={26}
+        dryBrushGap={0.28}
+        showLiveInkAccents={true}
+        interactiveBrush={true}
+        showTouchControls={true}
+      />
+    </div>
+  );
+}
+```
+
+| Propriedade | Tipo | Padrão | Descrição |
+| :--- | :--- | :--- | :--- |
+| `src` | `string` | Obra Monte Fuji | URL ou Data URI da imagem a ser revelada pela máscara caligráfica. |
+| `choreography` | `MaskChoreography` | `'fuji_masterpiece'` | Coreografia da revelação (`'fuji_masterpiece'`, `'katana_slashes'`, `'hokusai_tide'`, `'enso_spiral'`, `'interactive_brush'`). |
+| `duration` | `number` | `3.4` | Duração da cerimônia de revelação em segundos. |
+| `bristleCount` | `number` | `26` | Quantidade de cerdas de bambu no pincel (8 a 40). |
+| `dryBrushGap` | `number` | `0.28` | Intensidade da textura de pincel seco *Kasure* (0.0 a 0.85). |
+| `interactiveBrush` | `boolean` | `true` | Permite tocar ou arrastar o dedo/mouse para pintar e revelar novas áreas. |
+| `showTouchControls` | `boolean` | `true` | Exibe a barra flutuante para alternar entre **Pintar do Zero (Toque)** e **Auto-Revelar**. |
+
+---
+
+### 2. `<SumiSansui />` · Paisagens Gerativas *Sansui* por Seed & Tema
+
+Gera pinturas orientais de montanhas e águas (*Shan-Shui* / *Sansui* 山水) 100% procedurais e determinísticas por `seed`, com cristas caligráficas variáveis, hachuras internas de rocha (*Cunfa* 皴法), neblina na base das montanhas, pinheiros em nanquim e barco solitário. Adapta-se a temas prontos, **Modo Noturno** (`night_obsidian`), **Cores Personalizadas** ou **Variáveis CSS** do seu projeto (`theme="auto"`).
+
+```tsx
+import { SumiSansui } from '@sumi-forge/react';
+
+export function GenerativeSansuiBanner() {
+  return (
+    <div className="w-full h-[380px] rounded-2xl overflow-hidden">
+      <SumiSansui
+        composition="panoramic_river" // 'panoramic_river' | 'karst_peaks' | 'layered_valley' | 'twin_gorges'
+        seed={8472}
+        theme="jade_mineral" // 'classic_washi' | 'jade_mineral' | 'night_obsidian' | 'crimson_dawn' | 'cobalt_porcelain' | 'auto'
+        ridgeLayers={5}
+        treeDensity={1.0}
+        mistDensity={1.0}
+        showBoat={true}
+        animated={true}
+      />
+    </div>
+  );
+}
+```
+
+| Propriedade | Tipo | Padrão | Descrição |
+| :--- | :--- | :--- | :--- |
+| `composition` | `SansuiComposition` | `'panoramic_river'` | Composição estrutural (`'panoramic_river'`, `'karst_peaks'`, `'layered_valley'`, `'twin_gorges'`). |
+| `seed` | `number` | `8472` | Semente numérica determinística: a mesma seed recria exatamente a mesma cordilheira e vegetação. |
+| `theme` | `SansuiThemeId` | `'classic_washi'` | Paleta pronta (`'classic_washi'`, `'jade_mineral'`, `'night_obsidian'`, `'crimson_dawn'`, `'cobalt_porcelain'`) ou `'auto'` (lê `--sumi-bg`, `--sumi-ink`, `--sumi-wash` e `.dark`). |
+| `backgroundColor` | `string` | `undefined` | Sobrescreve livremente a cor de fundo do pergaminho. |
+| `inkColor` | `string` | `undefined` | Sobrescreve livremente a cor dos traços de contorno, hachuras e árvores. |
+| `washColor` | `string` | `undefined` | Sobrescreve livremente a cor da aguada mineral interna das montanhas. |
+| `ridgeLayers` | `number` | `5` | Quantidade de planos atmosféricos de montanhas (2 a 8). |
+| `treeDensity` | `number` | `1.0` | Densidade de pinheiros e árvores caligráficas nas encostas (0.0 a 2.0). |
+| `showBoat` | `boolean` | `true` | Exibe a embarcação solitária deslizando nas águas calmas. |
+
+---
+
+### 3. `<SumiLandscape />` · Paisagem 100% Procedural do Monte Fuji & Sakura
+
+Renderiza a cena viva do Monte Fuji, Sol Vermelho, Ilha de Pinheiros e Galho de Cerejeira com pétalas reagindo à brisa e ao cursor/toque.
+
+```tsx
+import { useRef } from 'react';
+import { SumiLandscape, DEFAULT_FUJI_LAYERS } from '@sumi-forge/react';
+
+export function LivingHeroBackground() {
+  const revealProgressRef = useRef<number>(1);
+
+  return (
+    <div className="w-full h-screen">
+      <SumiLandscape
+        revealProgressRef={revealProgressRef}
+        layers={DEFAULT_FUJI_LAYERS}
+        windSpeed={1.05}
+        animated={true}
+        interactive={true}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 3. `<SumiBrushCanvas />` · Atelier de Pintura com Pressão Real
+
+Tela de pintura multi-camadas em papel Washi com 6 estilos de pincéis orientais e suporte completo a toque no celular.
+
+```tsx
+import { SumiBrushCanvas, MAGIC_SCHOOLS } from '@sumi-forge/react';
+
+export function InteractivePaintingPad() {
+  return (
+    <div className="w-full h-[460px] rounded-xl overflow-hidden">
+      <SumiBrushCanvas
+        activeBrush="sakura_branch" // 'sakura_branch' | 'sumi_kasure' | 'hokusai_wave' | 'suibokuga_flame' | 'kumo_cloud' | 'tarashikomi_wash'
+        colors={MAGIC_SCHOOLS.fuji_sakura.colors}
+        strokeThickness={1.3}
+        bristleCount={26}
+        dryBrushGap={0.32}
+        activeLayer="foreground"
+        showReferenceGuide={true}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+### 4. `<SumiSectionPainter />` · Cenários que Pintam no Scroll
+
+Pinta fundos de seção sincronizados com a rolagem da página (Galhos de Sakura, Rio de Carpas Koi, Cordilheiras na Neblina e Selo Imperial Ensō).
+
+```tsx
+import { useRef } from 'react';
+import { SumiSectionPainter } from '@sumi-forge/react';
+
+export function KoiRiverSection() {
+  const scrollProgressRef = useRef<number>(0.65);
+
+  return (
+    <section className="relative py-24 overflow-hidden">
+      <div className="absolute inset-0 z-0">
+        <SumiSectionPainter
+          theme="koi_river_rapids" // 'sakura_katana_canopy' | 'koi_river_rapids' | 'misty_mountains_sakura' | 'enso_imperial_seal'
+          scrollProgressRef={scrollProgressRef}
+          school="calligraphy_tide"
+        />
+      </div>
+      <div className="relative z-10">
+        {/* Conteúdo da seção com cards em glassmorphismo */}
+      </div>
+    </section>
+  );
+}
+```
+
+---
+
+### 5. `<SumiButton />`, `<SumiIcon />` & `<JapaneseCalligraphy />`
+
+Componentes de interface desenhados à mão com estética Samurai e selos japoneses (*Hanko*) com tradução interativa para Português Brasileiro ao tocar ou passar o mouse.
+
+```tsx
+import { SumiButton, SumiIcon, JapaneseCalligraphy } from '@sumi-forge/react';
+
+export function SamuraiHeaderActions() {
+  return (
+    <div className="flex items-center gap-3">
+      <JapaneseCalligraphy
+        jp="花鳥風月"
+        romaji="Kachō Fūgetsu"
+        pt="Contemplar a beleza da natureza, das flores, do vento e da lua"
+        variant="hanko"
+      />
+
+      <SumiButton variant="crimson" size="md">
+        <SumiIcon name="brush" size={18} color="#11100E" />
+        <span>Abrir Playground</span>
+      </SumiButton>
+    </div>
+  );
+}
+```
+
+---
+
+## Pintura e Revelação no Mobile
+
+O `@sumi-forge/react` foi projetado para oferecer uma experiência tátil de primeira classe em smartphones e tablets:
+
+1. **Bloqueio Inteligente de Gestos (`touch-action: none`)**: Ao deslizar o dedo sobre o `<SumiMaskReveal />` ou `<SumiBrushCanvas />`, a página não rola acidentalmente, garantindo traços contínuos e precisos.
+2. **Toque Simples (*Single-Tap Stamp*)**: Um único toque na tela do celular estampa automaticamente uma mancha de aquarela *Tarashikomi* acompanhada por um golpe caligráfico e flores de cerejeira.
+3. **Modo "Pintar do Zero (Toque)"**: Limpa a máscara automática e exibe uma suave silhueta em papel Washi (12% de opacidade) para que o usuário revele a obra inteira passando o dedo na tela.
+4. **Traços Iniciais Responsivos**: No Atelier, a composição inicial do Monte Fuji e Sakura redimensiona suas coordenadas proporcionalmente à tela do celular.
+
+---
+
+## Desenvolvimento Local
+
+```bash
+# 1. Instale as dependências
+npm install
+
+# 2. Inicie o servidor de desenvolvimento (porta 3000)
+npm run dev
+
+# 3. Verifique a tipagem e o build de produção
+npm run lint
+npm run build
+```
+
+---
+
+## Documentação e Governança do Projeto
+
+- [Guia de Contribuição (`CONTRIBUTING.md`)](./CONTRIBUTING.md)
+- [Código de Conduta (`CODE_OF_CONDUCT.md`)](./CODE_OF_CONDUCT.md)
+- [Template de Pull Request (`.github/PULL_REQUEST_TEMPLATE.md`)](./.github/PULL_REQUEST_TEMPLATE.md)
+- [Licença Apache 2.0 (`LICENSE.md`)](./LICENSE.md)
+
+---
+
+<div align="center">
+
+**墨 SumiForge · `@sumi-forge/react`**  
+*made with love in Japa.... ops, Brazil* 🇧🇷 ❤️ 🇯🇵
+
+</div>

package/dist-lib/components/JapaneseCalligraphy.d.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+export type TooltipPlacement = 'top' | 'bottom' | 'left' | 'right';
+export interface JapaneseCalligraphyProps {
+    /** Caracteres em Japonês (Kanji) */
+    jp: string;
+    /** Leitura Romaji opcional */
+    romaji?: string;
+    /** Significado auspicioso em Português-Brasileiro exibido no modal/tooltip ao passar o mouse */
+    pt: string;
+    /** Estilo visual: selo vermelho Hanko, caligrafia vertical Tategaki ou texto inline */
+    variant?: 'hanko' | 'tategaki' | 'inline';
+    /** Direção controlada onde o modal/tooltip de tradução deve aparecer */
+    tooltipPlacement?: TooltipPlacement;
+    className?: string;
+}
+/**
+ * Componente <JapaneseCalligraphy /> — Mantém os ideogramas japoneses intactos no layout
+ * e exibe a tradução em Português-Brasileiro dentro de um pequeno modal/tooltip flutuante
+ * com direção controlada (top, bottom, left, right) e proteção automática contra fuga da tela.
+ */
+export declare const JapaneseCalligraphy: React.FC<JapaneseCalligraphyProps>;

package/dist-lib/components/SumiBrushCanvas.d.ts

@@ -0,0 +1,41 @@
+import React from 'react';
+import { InteractiveBrushType, SumiColors } from '../types';
+export interface SumiBrushCanvasProps {
+    /** Tipo de pincel selecionado */
+    activeBrush?: InteractiveBrushType;
+    /** Paleta de cores atual */
+    colors?: SumiColors;
+    /** Multiplicador de espessura do pincel (0.4 a 2.5) */
+    strokeThickness?: number;
+    /** Quantidade de cerdas de bambu (6 a 40) */
+    bristleCount?: number;
+    /** Intensidade de falha de pincel seco Kasure (0.0 a 0.85) */
+    dryBrushGap?: number;
+    /** Camada onde os novos traços serão gravados */
+    activeLayer?: 'background' | 'midground' | 'foreground';
+    /** Opacidade individual de cada camada */
+    layerOpacities?: {
+        background: number;
+        midground: number;
+        foreground: number;
+    };
+    /** Exibe o guia translúcido da obra Monte Fuji & Sakura ao fundo */
+    showReferenceGuide?: boolean;
+    /** Callback de telemetria de pressão e velocidade em tempo real */
+    onTelemetryChange?: (telemetry: {
+        pressure: number;
+        velocity: number;
+        strokeCount: number;
+        isReplaying: boolean;
+    }) => void;
+    /** Referência imperativa para ações externas (replay, limpar, desfazer, exportar PNG) */
+    actionsRef?: React.MutableRefObject<{
+        replayStrokes: () => void;
+        undoStroke: () => void;
+        clearCanvas: () => void;
+        loadFujiPresetStrokes: () => void;
+        exportPng: () => void;
+    } | null>;
+    className?: string;
+}
+export declare const SumiBrushCanvas: React.FC<SumiBrushCanvasProps>;

package/dist-lib/components/SumiButton.d.ts

@@ -0,0 +1,32 @@
+import React from 'react';
+export type SumiButtonVariant = 'crimson' | 'ink' | 'washi' | 'ghost' | 'outline';
+export type SumiButtonSize = 'xs' | 'sm' | 'md' | 'lg';
+export interface SumiButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Estilo visual da caixa caligráfica */
+    variant?: SumiButtonVariant;
+    /** Tamanho e espaçamento interno */
+    size?: SumiButtonSize;
+    /** Estado ativo para abas e seletores */
+    active?: boolean;
+    /** Semente determinística para o traço Rough.js */
+    seed?: number;
+    /** Ocupar 100% da largura disponível */
+    fullWidth?: boolean;
+    children: React.ReactNode;
+}
+/**
+ * Componente <SumiButton />
+ * Botão retangular de bordas retas desenhadas com Rough.js, inspirado em selos e placas
+ * de xilogravura japonesa, com performance instantânea via cache de caminhos SVG.
+ */
+export declare const SumiButton: React.FC<SumiButtonProps>;
+export interface SumiRoughBoxProps extends React.HTMLAttributes<HTMLDivElement> {
+    strokeColor?: string;
+    innerAccentColor?: string | null;
+    seed?: number;
+    children: React.ReactNode;
+}
+/**
+ * Container retangular com borda reta desenhada por Rough.js (ideal para barras de comando, grupos de abas e selos).
+ */
+export declare const SumiRoughBox: React.FC<SumiRoughBoxProps>;

package/dist-lib/components/SumiIcon.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+export type SumiIconName = 'logo' | 'brush' | 'katana' | 'sakura' | 'koi' | 'mountain' | 'scroll' | 'play' | 'pause' | 'replay' | 'copy' | 'check' | 'download' | 'upload' | 'undo' | 'trash' | 'eye' | 'layers' | 'sliders' | 'chevron-down' | 'close' | 'terminal';
+export interface SumiIconProps {
+    name: SumiIconName;
+    size?: number;
+    color?: string;
+    accentColor?: string;
+    seed?: number;
+    className?: string;
+}
+/**
+ * Componente <SumiIcon /> — Desenha todos os ícones da interface em nanquim monocromático
+ * nítido usando Rough.js (preserveVertices: true), mantendo estética orgânica de traço à mão
+ * com leitura imediata.
+ */
+export declare const SumiIcon: React.FC<SumiIconProps>;
+export interface SumiBrandEmblemProps {
+    size?: number;
+    className?: string;
+}
+/**
+ * Emblema Japonês Pintado (<SumiBrandEmblem />) — Pinta o círculo Ensō em nanquim,
+ * o sol carmesim e o ideograma 墨 (Sumi: Nanquim) à mão usando as técnicas da biblioteca.
+ */
+export declare const SumiBrandEmblem: React.FC<SumiBrandEmblemProps>;

package/dist-lib/components/SumiLandscape.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+import { SumiColors, SumiLayerIntensities } from '../types';
+export interface SumiLandscapeProps {
+    /** Progresso de pintura animada (0.0 a 1.0). Se omitido, anima automaticamente ao montar */
+    revealProgress?: number;
+    /** Referência mutável opcional para atualizar o progresso sem re-renderizar o React */
+    revealProgressRef?: React.MutableRefObject<number | undefined>;
+    /** Controle granular de intensidade de cada camada artística (0.0 a 1.5) */
+    layers?: Partial<SumiLayerIntensities>;
+    /** Paleta cromática (padrão: Monte Fuji & Sakura Carmesim da referência) */
+    colors?: Partial<SumiColors>;
+    /** Semente determinística Mulberry32 */
+    seed?: number;
+    /** Se verdadeiro, anima continuamente pétalas de Sakura ao vento e reflexos solares na água */
+    animated?: boolean;
+    /** Velocidade da brisa das pétalas e água */
+    windSpeed?: number;
+    /** Classe CSS adicional */
+    className?: string;
+    /** Callback ao mover o cursor na cena para paralaxe sutil */
+    interactive?: boolean;
+}
+/**
+ * Componente <SumiLandscape />
+ * Recria de forma 100% procedural, responsiva e animada a obra japonesa do Monte Fuji,
+ * Sol Vermelho, Galho de Sakura e Ilha de Pinheiros.
+ *
+ * Abertura em 3 atos fluidos a 60/120 FPS (sem engasgos):
+ * 1. O Sol Vermelho surge e se espalha como uma mancha de tinta úmida (Tarashikomi) no papel Washi.
+ * 2. Os traços de nanquim do Galho de Sakura, do Monte Fuji e da Ilha de Pinheiros deslizam pela tela.
+ * 3. Após o traço do galho estar pintado, as flores de Sakura brotam como manchas de aquarela carmesim.
+ */
+export declare const SumiLandscape: React.FC<SumiLandscapeProps>;

package/dist-lib/components/SumiMaskReveal.d.ts

@@ -0,0 +1,39 @@
+import React from 'react';
+import { MaskChoreography } from '../types';
+export interface SumiMaskRevealProps {
+    /** URL da imagem a ser pintada/revelada com a máscara de pinceladas (padrão: obra do Monte Fuji e Sakura) */
+    src?: string;
+    /** Texto alternativo para acessibilidade */
+    alt?: string;
+    /** Coreografia das pinceladas que revelam a imagem */
+    choreography?: MaskChoreography;
+    /** Duração total da animação de pintura em segundos */
+    duration?: number;
+    /** Quantidade de cerdas de bambu por pincelada (Técnica #03) */
+    bristleCount?: number;
+    /** Intensidade de falha de pincel seco Kasure (0.0 a 0.85) */
+    dryBrushGap?: number;
+    /** Semente determinística Mulberry32 */
+    seed?: number;
+    /** Se verdadeiro, exibe os acentos vivos de tinta úmida e pétalas sobre a imagem revelada */
+    showLiveInkAccents?: boolean;
+    /** Modo Raio-X para visualizar apenas a máscara de pinceladas pura */
+    maskOnlyPreview?: boolean;
+    /** Progresso controlado externamente (0.0 a 1.0). Se omitido, anima automaticamente */
+    progress?: number;
+    /** Chave de gatilho para reiniciar a pintura do zero */
+    replayTrigger?: number;
+    /** Permite ao usuário pintar/revelar ainda mais com o dedo, mouse ou caneta */
+    interactiveBrush?: boolean;
+    /** Exibe controles rápidos flutuantes para pintar com o dedo no mobile/desktop */
+    showTouchControls?: boolean;
+    /** Classe CSS do container */
+    className?: string;
+}
+/**
+ * Componente <SumiMaskReveal />
+ * Realiza a pintura animada de qualquer imagem passada via prop `src` combinando máscara de pinceladas
+ * Multi-Cerdas Kasure, Aguada Tarashikomi e Canvas Composite (`destination-in`), com cache offscreen
+ * e suporte completo a pintura por toque no mobile (arrastar ou tocar para revelar).
+ */
+export declare const SumiMaskReveal: React.FC<SumiMaskRevealProps>;

package/dist-lib/components/SumiSansui.d.ts

@@ -0,0 +1,40 @@
+import React from 'react';
+import { SansuiColors, SansuiComposition, SansuiThemeId } from '../types';
+export interface SumiSansuiProps {
+    /** Semente determinística Mulberry32: cada número gera uma paisagem única e reproduzível */
+    seed?: number;
+    /** Estilo de composição clássica Sansui (山水) */
+    composition?: SansuiComposition;
+    /** Tema pronto de cores (inclui Modo Noturno 'night_obsidian', 'jade_mineral', 'classic_washi' ou 'auto') */
+    theme?: SansuiThemeId;
+    /** Sobrescrita livre de cores (permite passar as cores da marca ou do tema do usuário) */
+    colors?: Partial<SansuiColors>;
+    /** Atalho para cor de fundo do papel/céu */
+    backgroundColor?: string;
+    /** Atalho para cor principal do nanquim / traços */
+    inkColor?: string;
+    /** Atalho para cor da aguada mineral das montanhas */
+    washColor?: string;
+    /** Quantidade de planos de montanhas (3 a 8) */
+    ridgeLayers?: number;
+    /** Densidade de pinheiros e árvores nas encostas (0.0 a 2.0) */
+    treeDensity?: number;
+    /** Intensidade da neblina entre os vales (0.0 a 1.5) */
+    mistDensity?: number;
+    /** Exibe o pescador solitário em seu barco (sampan) */
+    showBoat?: boolean;
+    /** Ativa o movimento sutil da água, da neblina e do barco */
+    animated?: boolean;
+    /** Referência opcional para exportar a pintura gerada em PNG de alta definição */
+    actionsRef?: React.MutableRefObject<{
+        exportPng: (filename?: string) => void;
+    } | null>;
+    /** Classe CSS adicional */
+    className?: string;
+}
+/**
+ * Componente <SumiSansui />
+ * Motor próprio de pintura gerativa de paisagens Sansui / Shan-Shui (山水) controlado por seed,
+ * com suporte a temas prontos, Modo Noturno, variáveis CSS e cores customizadas.
+ */
+export declare const SumiSansui: React.FC<SumiSansuiProps>;

package/dist-lib/components/SumiSectionPainter.d.ts

@@ -0,0 +1,24 @@
+import React from 'react';
+import { SchoolId } from '../types';
+export type SectionPaintingTheme = 'header_single_stroke' | 'sakura_katana_canopy' | 'koi_river_rapids' | 'misty_mountains_sakura' | 'enso_imperial_seal';
+export interface SumiSectionPainterProps {
+    /** Cena artística japonesa pintada pelo pacote */
+    theme: SectionPaintingTheme;
+    /** Progresso de pintura controlado pelo scroll GSAP ou animação (0.0 a 1.0) */
+    scrollProgress?: number;
+    /** Referência mutável opcional para atualizar progresso sem re-renderizar o React */
+    scrollProgressRef?: React.MutableRefObject<number>;
+    /** Paleta cromática ativa */
+    school?: SchoolId;
+    /** Semente determinística */
+    seed?: number;
+    /** Movimento orgânico contínuo (vento, água, nado das carpas) */
+    ambientMotion?: boolean;
+    className?: string;
+}
+/**
+ * Componente <SumiSectionPainter />
+ * Pinta cenas completas de pergaminho japonês sincronizadas com o scroll.
+ * Utiliza cache em canvas offscreen e IntersectionObserver para manter 60/120 FPS com uso mínimo de CPU.
+ */
+export declare const SumiSectionPainter: React.FC<SumiSectionPainterProps>;

package/dist-lib/components/SumiStroke.d.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+export interface SumiStrokeProps {
+    /** Estilo da pincelada decorativa ou divisor de seção */
+    variant?: 'horizontal_kasure' | 's_curve_flourish' | 'enso_seal' | 'sakura_branch_divider';
+    /** Cor primária do nanquim */
+    inkColor?: string;
+    /** Cor secundária de acento (ex: vermelho Sakura / Hanko) */
+    accentColor?: string;
+    /** Quantidade de cerdas */
+    bristleCount?: number;
+    /** Falha de pincel seco Kasure */
+    dryBrushGap?: number;
+    /** Espessura máxima em pixels */
+    thickness?: number;
+    /** Semente determinística */
+    seed?: number;
+    /** Anima a pincelada ao montar */
+    animateOnMount?: boolean;
+    className?: string;
+}
+/**
+ * Componente <SumiStroke /> — Pincelada caligráfica declarativa para divisores de seção,
+ * sublinhados editoriais, selos Ensō e ramos ornamentais de Sakura.
+ */
+export declare const SumiStroke: React.FC<SumiStrokeProps>;

package/dist-lib/components/SumiVFX.d.ts

@@ -0,0 +1,23 @@
+import React from 'react';
+import { VFXConfig } from '../types';
+export interface SumiVFXProps {
+    /** Configuração parcial ou completa do efeito Sakuga */
+    config?: Partial<VFXConfig>;
+    /** Modo de exibição: animação contínua ('player') ou folha de sprites 4x4 ('spritesheet') */
+    mode?: 'player' | 'spritesheet';
+    /** Quadro fixo opcional [0..15]. Se omitido, anima continuamente na taxa `fps` */
+    fixedFrame?: number | null;
+    /** Resolução do canvas em pixels */
+    size?: number;
+    /** Se verdadeiro, pausa a reprodução automática */
+    paused?: boolean;
+    /** Callback por frame para sincronizar UI externa */
+    onFrameTick?: (frameIndex: number) => void;
+    className?: string;
+}
+/**
+ * Componente <SumiVFX />
+ * Renderizador declarativo de efeitos procedurais de 16 quadros com Cinética Sakuga.
+ * Redesenha apenas quando o quadro avança (ex: 16 FPS) e pausa automaticamente fora da viewport.
+ */
+export declare const SumiVFX: React.FC<SumiVFXProps>;

package/dist-lib/gifEncoder.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Técnica #12: Codificador Binário GIF89a LZW Completo
+ * Quantização de paleta 6x6x6 (216 cores) + índice dedicado de transparência (255),
+ * Graphics Control Extension (0x21 0xF9) com Disposal Method = 2 (Restore to Background),
+ * e compressão LZW de código variável (9 a 12 bits) sem dependências externas.
+ */
+export declare function encodeAnimatedGIF89a(frames: ImageData[], width: number, height: number, fps: number): Uint8Array;