@sumi-forge/react 0.0.0-stage → 1.0.1

package/dist-lib/math.d.ts

@@ -0,0 +1,68 @@
+import { Point2D, VFXConfig } from './types';
+/**
+ * Técnica #01: PRNG Determinístico (Mulberry32)
+ * Estado inteiro de 32 bits incrementado por 0x6D2B79F5 a cada chamada,
+ * garantindo coerência temporal entre todos os quadros sem cintilação (flicker).
+ */
+export declare function createSeededRandom(seed: number): () => number;
+/**
+ * Técnica #01: Value Noise 2D suavizado por curva Hermite cúbica (Smoothstep)
+ * u = xf² · (3 - 2·xf) e v = yf² · (3 - 2·yf)
+ */
+export declare function sampleNoise2D(x: number, y: number, seed: number): number;
+/**
+ * Técnica #01: FBM 2D de 3 Oitavas
+ * FBM(x, y, seed) = 0.55 · N(x, y, s) + 0.30 · N(2.15x + 13.7, 2.15y + 7.3, s + 101) + 0.15 · N(4.4x - 5.2, 4.4y + 19.1, s + 307)
+ */
+export declare function fbmNoise2D(x: number, y: number, seed: number): number;
+/**
+ * Técnica #02: Amostrador de Curva Bézier Cúbica (S-Curve) com Vetores Normais Analíticos
+ */
+export declare function sampleCubicCurve(p0: {
+    x: number;
+    y: number;
+}, p1: {
+    x: number;
+    y: number;
+}, p2: {
+    x: number;
+    y: number;
+}, p3: {
+    x: number;
+    y: number;
+}, steps?: number, jitterAmount?: number, seed?: number): Point2D[];
+/**
+ * Técnica #02: Amostrador de Curva Bézier Quadrática com Normais Analíticas
+ */
+export declare function sampleQuadraticCurve(p0: {
+    x: number;
+    y: number;
+}, p1: {
+    x: number;
+    y: number;
+}, p2: {
+    x: number;
+    y: number;
+}, steps?: number, jitterAmount?: number, seed?: number): Point2D[];
+/**
+ * Técnica #02: Arco Polar / Elíptico com Tilt 3D e Fator Espiral
+ */
+export declare function samplePolarArc(cx: number, cy: number, rx: number, ry: number, startAngle: number, endAngle: number, tiltRadians?: number, spiralFactor?: number, steps?: number, jitterAmount?: number, seed?: number): Point2D[];
+/**
+ * Converte amostras de ponteiro do usuário em uma espinha dorsal Point2D suavizada
+ */
+export declare function samplesToSpine(rawPoints: {
+    x: number;
+    y: number;
+}[], jitterAmount?: number, seed?: number): Point2D[];
+export declare function hexToRgb(hex: string): [number, number, number];
+export declare function rgbaStr(hex: string, alpha: number): string;
+export declare function mixHex(hexA: string, hexB: string, t: number): string;
+/**
+ * Técnica #11: Shader de Recolorização por Separação de 3 Canais (CPU ImageData & GPU Shader Equivalente)
+ * L = 0.299·R + 0.587·G + 0.114·B
+ * W_core = (min(R, G, B))^2.2
+ * W_energy = clamp(chroma * 2.1 + max(0, L - 0.18) * (1 - W_core), 0, 1)
+ * W_ink = max(0, 1 - W_energy - W_core)
+ */
+export declare function recolorReferenceSheetData(src: ImageData, config: VFXConfig): ImageData;

package/dist-lib/presets.d.ts

@@ -0,0 +1,21 @@
+import { ArchetypeId, MagicSchool, SansuiComposition, SansuiThemeId, SansuiThemePreset, SchoolId, SumiLayerIntensities, TechniqueSpec, VFXConfig } from './types';
+export declare const SANSUI_THEMES: Record<Exclude<SansuiThemeId, 'auto'>, SansuiThemePreset>;
+export declare const SANSUI_COMPOSITIONS: {
+    id: SansuiComposition;
+    name: string;
+    jp: string;
+    romaji: string;
+    ptMeaning: string;
+    description: string;
+}[];
+export declare const MAGIC_SCHOOLS: Record<SchoolId, MagicSchool>;
+export declare const ARCHETYPE_CATALOG: {
+    id: ArchetypeId;
+    name: string;
+    category: string;
+    defaultSchool: SchoolId;
+    description: string;
+}[];
+export declare const DEFAULT_VFX_CONFIG: VFXConfig;
+export declare const DEFAULT_FUJI_LAYERS: SumiLayerIntensities;
+export declare const TECHNIQUES_CATALOG: TechniqueSpec[];

package/dist-lib/techniques.d.ts

@@ -0,0 +1,107 @@
+import rough from 'roughjs';
+import type { Options as RoughOptions } from 'roughjs/bin/core';
+import { Point2D, SumiColors, VFXConfig } from './types';
+type RoughCanvasInstance = ReturnType<typeof rough.canvas>;
+/**
+ * Técnica #10: Opções Determinísticas para Rough.js
+ */
+export declare function makeFineRoughOptions(config: VFXConfig, scale: number, seedOffset: number, overrides?: Partial<RoughOptions>): RoughOptions;
+/**
+ * Técnica #03 & #04: Fita Caligráfica Multi-Cerdas Sumi-e com Efeito Kasure (Flying-White)
+ * + Erosão Celular Progressiva por Limiar de Ruído FBM 2D
+ */
+export interface KasureRibbonOpts {
+    spine: Point2D[];
+    maxWidth: number;
+    bristleCount: number;
+    dryBrushGap: number;
+    taperStart: number;
+    taperEnd: number;
+    color: string;
+    alpha?: number;
+    offsetNormal?: number;
+    headReach?: number;
+    tailRetract?: number;
+    erosionProgress?: number;
+    erosionScale?: number;
+    hookWaves?: number;
+    roundHeadCap?: boolean;
+    seed: number;
+}
+export declare function drawSumiKasureRibbon(ctx: CanvasRenderingContext2D, opts: KasureRibbonOpts): void;
+/**
+ * Técnica #04: Gotas Centrífugas Alongadas na Direção Tangente + Normal
+ */
+export declare function drawCentrifugalSplatters(ctx: CanvasRenderingContext2D, spine: Point2D[], frameNorm: number, splatterCount: number, splatterSpread: number, scale: number, colors: SumiColors, seed: number): void;
+/**
+ * Técnica #05: Pétalas de Chama Aquareladas em S-Curve com Estrias Fibrosas & Fitas Desprendidas
+ */
+export interface FlamePetalTongueOpts {
+    rootX: number;
+    rootY: number;
+    ctrl1X: number;
+    ctrl1Y: number;
+    ctrl2X: number;
+    ctrl2Y: number;
+    tipX: number;
+    tipY: number;
+    maxBellyWidth: number;
+    striationCount?: number;
+    alpha?: number;
+    seed: number;
+}
+export declare function drawFlamePetalTongue(ctx: CanvasRenderingContext2D, rc: RoughCanvasInstance | null, config: VFXConfig, scale: number, opts: FlamePetalTongueOpts): void;
+export declare function drawDetachedSumiFlameWisp(ctx: CanvasRenderingContext2D, startX: number, startY: number, endX: number, endY: number, width: number, color: string, seed: number): void;
+/**
+ * Técnica #06: Cristas de Onda Ukiyo-e (Hokusai), 5 Correntes Listradas & Garras Fractais de Espuma
+ */
+export declare function drawHokusaiFoamClawCluster(ctx: CanvasRenderingContext2D, rc: RoughCanvasInstance | null, cx: number, cy: number, baseAngle: number, curlDir: 1 | -1, clawCount: number, radius: number, config: VFXConfig, scale: number, seed: number): void;
+export declare function drawHokusaiWaveCrest(ctx: CanvasRenderingContext2D, rc: RoughCanvasInstance | null, spine: Point2D[], maxWidth: number, curlDir: 1 | -1, clawCount: number, config: VFXConfig, scale: number, alpha: number, seed: number): void;
+/**
+ * Técnica #07: Bancos de Nuvens & Fumaça Ukiyo-e (Kumo) com Volutas em C-Hook e Caracóis Internos
+ */
+export interface KumoVoluteOpts {
+    startX: number;
+    startY: number;
+    endX: number;
+    endY: number;
+    maxThickness: number;
+    lobeCount?: number;
+    curlRadius?: number;
+    flip?: 1 | -1;
+    alpha?: number;
+    seed: number;
+}
+export declare function drawUkiyoeCloudScrollVolute(ctx: CanvasRenderingContext2D, rc: RoughCanvasInstance | null, config: VFXConfig, scale: number, opts: KumoVoluteOpts): void;
+export declare function drawUkiyoeCloudBank(ctx: CanvasRenderingContext2D, rc: RoughCanvasInstance | null, cx: number, cy: number, spanWidth: number, puffCount: number, config: VFXConfig, scale: number, alpha: number, seed: number): void;
+/**
+ * Técnica #08: Núcleo Sólido 100% Opaco com Oclusão Real (Alpha 1.0 em todas as paradas)
+ */
+export declare function drawSolidOpaqueCoreSphere(ctx: CanvasRenderingContext2D, rc: RoughCanvasInstance | null, cx: number, cy: number, rx: number, ry: number, dirAngle: number, wobbleAmount: number, config: VFXConfig, scale: number, seed: number): void;
+/**
+ * Técnica #09: Aguada Suibokuga (Tarashikomi) com Borda de Sangria de Pigmento
+ */
+export declare function drawTarashikomiWashBlob(ctx: CanvasRenderingContext2D, cx: number, cy: number, rx: number, ry: number, rotation: number, coreColor: string, edgeColor: string, alpha: number, seed: number): void;
+/**
+ * Técnica #10: Geometria Poligonal Sólida Hand-Made com Rough.js (Cristais Chanfrados Cel-Shaded)
+ */
+export declare function drawFacetedRoughCrystal(ctx: CanvasRenderingContext2D, rc: RoughCanvasInstance | null, baseX: number, baseY: number, angle: number, length: number, width: number, config: VFXConfig, scale: number, seed: number): void;
+/**
+ * Flor de Sakura (Cerejeira) Aquarelada Suibokuga com 5 pétalas chanfradas e estames
+ */
+export declare function drawSakuraBlossom(ctx: CanvasRenderingContext2D, cx: number, cy: number, radius: number, rotation: number, petalColor: string, coreColor: string, inkColor: string, alpha?: number, seed?: number): void;
+/**
+ * Pétala Individual de Sakura Flutuando ao Vento
+ */
+export declare function drawFloatingSakuraPetal(ctx: CanvasRenderingContext2D, x: number, y: number, size: number, angle: number, tiltRatio: number, color: string, alpha?: number): void;
+/**
+ * Carpa Japonesa (Nishikigoi / Kohaku) pintada a pincel Sumi-e & Suibokuga
+ * Corpo em curva S fluida, nadadeiras peitorais caligráficas, manchas vermelhas e ondulações de rio.
+ */
+export declare function drawCalligraphicKoiCarp(ctx: CanvasRenderingContext2D, cx: number, cy: number, length: number, angle: number, swimPhase: number, inkColor: string, crimsonColor: string, bodyLightColor: string, alpha?: number, seed?: number): void;
+/**
+ * Galho Ornamental de Sakura (Cerejeira) com Sub-Ramos e Cachos de Flores
+ * Usado para emoldurar cantos e seções com elegância orgânica japonesa.
+ */
+export declare function drawCornerSakuraBranch(ctx: CanvasRenderingContext2D, startX: number, startY: number, endX: number, endY: number, archDir: 1 | -1, maxTrunkWidth: number, reachProgress: number, swayTime: number, inkColor: string, petalColor: string, coreColor: string, seed: number): void;
+export {};

package/dist-lib/types.d.ts

@@ -0,0 +1,129 @@
+export type SchoolId = 'fuji_sakura' | 'calligraphy_tide' | 'fungal_emerald' | 'toxic_venom' | 'abyssal_curse' | 'blood_shadow' | 'necro_phantom' | 'capoeira_dende' | 'abyssal_flame' | 'celestial_thunder' | 'astral_gold';
+export type ArchetypeId = 'hyb_slash_great_wave_katana' | 'hyb_slash_crimson_phoenix_arc' | 'hyb_slash_blood_moon_scythe' | 'crescent' | 'water_slash' | 'enso_sigil' | 'elem_fire_meteor_bolide' | 'elem_water_glacial_spikes' | 'solid_ref_fumaca' | 'elem_water_healing_fountain' | 'sakura_tempest_slash' | 'portal_abyssal_vortex';
+export type ChannelMode = 'composite' | 'ink_only' | 'energy_only' | 'shader_rgb_mask';
+export type BgMode = 'washi' | 'checker' | 'dark' | 'transparent';
+export type RoughFillStyle = 'solid' | 'hachure' | 'cross-hatch' | 'zigzag';
+export interface Point2D {
+    x: number;
+    y: number;
+    nx: number;
+    ny: number;
+    t: number;
+}
+export interface SumiColors {
+    inkPrimary: string;
+    energySecondary: string;
+    coreGlow: string;
+    sporeAccent: string;
+}
+export interface SumiBrushConfig {
+    bristleCount: number;
+    strokeThickness: number;
+    taperStart: number;
+    taperEnd: number;
+    dryBrushGap: number;
+    curvature: number;
+    angle: number;
+    arcSweep: number;
+}
+export interface SumiDynamicsConfig {
+    splatterCount: number;
+    splatterSpread: number;
+    hookWaves: number;
+    erosionStrength: number;
+    erosionScale: number;
+    glowIntensity: number;
+    colorOffset: number;
+    jitterAmount: number;
+}
+export interface SumiRoughConfig {
+    roughness: number;
+    bowing: number;
+    outlineWidth: number;
+    fillStyle: RoughFillStyle;
+    celSteps: number;
+}
+export interface SumiLayerIntensities {
+    sunIntensity: number;
+    mountainIntensity: number;
+    sakuraBranchIntensity: number;
+    sakuraPetalsIntensity: number;
+    waterReflectionIntensity: number;
+    mistKumoIntensity: number;
+}
+export interface VFXConfig {
+    archetype: ArchetypeId;
+    school: SchoolId;
+    colors: SumiColors;
+    bgMode: BgMode;
+    channelMode: ChannelMode;
+    brush: SumiBrushConfig;
+    dynamics: SumiDynamicsConfig;
+    rough: SumiRoughConfig;
+    totalFrames: number;
+    fps: number;
+    seed: number;
+    frameSize: 96 | 128 | 192 | 256;
+}
+export interface MagicSchool {
+    id: SchoolId;
+    name: string;
+    elementStyle: string;
+    colors: SumiColors;
+}
+export interface TechniqueSpec {
+    id: number;
+    code: string;
+    title: string;
+    subtitle: string;
+    origin: string;
+    archetype: ArchetypeId;
+    school: SchoolId;
+    equations: string[];
+    invariantsDo: string[];
+    invariantsDont: string[];
+    description: string;
+}
+export type InteractiveBrushType = 'sumi_kasure' | 'sakura_branch' | 'hokusai_wave' | 'suibokuga_flame' | 'kumo_cloud' | 'tarashikomi_wash' | 'rough_crystal';
+export interface BrushPointSample {
+    x: number;
+    y: number;
+    pressure: number;
+    velocity: number;
+    timestamp: number;
+}
+export interface RecordedBrushStroke {
+    id: string;
+    brushType: InteractiveBrushType;
+    points: BrushPointSample[];
+    colors: SumiColors;
+    thickness: number;
+    bristleCount: number;
+    dryBrushGap: number;
+    seed: number;
+    layerId: 'background' | 'midground' | 'foreground';
+}
+export type MaskChoreography = 'fuji_masterpiece' | 'katana_slashes' | 'enso_spiral' | 'hokusai_tide' | 'interactive_brush';
+export type SansuiComposition = 'panoramic_river' | 'karst_peaks' | 'layered_valley' | 'twin_gorges';
+export type SansuiThemeId = 'classic_washi' | 'jade_mineral' | 'night_obsidian' | 'crimson_dawn' | 'cobalt_porcelain' | 'auto';
+export interface SansuiColors {
+    /** Cor do papel / céu e extensão das águas */
+    background: string;
+    /** Cor principal do nanquim / contorno caligráfico das cristas, árvores e barco */
+    ink: string;
+    /** Cor da aguada mineral ou sombreado interno das montanhas */
+    wash: string;
+    /** Cor da neblina atmosférica que separa os planos de profundidade */
+    mist: string;
+    /** Cor de acento opcional (folhagem, sol discreto ou selo) */
+    accent: string;
+}
+export interface SansuiThemePreset {
+    id: Exclude<SansuiThemeId, 'auto'>;
+    name: string;
+    jp: string;
+    romaji: string;
+    subtitle: string;
+    isDark?: boolean;
+    colors: SansuiColors;
+}

package/dist-lib/vfxRenderer.d.ts

@@ -0,0 +1,13 @@
+import { VFXConfig } from './types';
+/**
+ * Renderiza um único quadro [0..15] no espaço canônico 128×128 multiplicado por scale = width / 128.
+ * Segue a Cinética Não-Linear de Ataque (Sakuga Timing):
+ * - Quadros 0..3 (frameNorm 0.00..0.20): Aceleração explosiva headReach = 1 - (1 - frameNorm)^3.4
+ * - Quadros 4..6 (frameNorm 0.25..0.40): Ápice de impacto com núcleo branco e extensão máxima
+ * - Quadros 7..15 (frameNorm 0.46..1.00): Erosão celular progressiva por FBM 2D + gotas centrífugas
+ */
+export declare function renderVFXFrame(ctx: CanvasRenderingContext2D, frameIndex: number, totalFrames: number, width: number, height: number, config: VFXConfig, transparentBg?: boolean): void;
+/**
+ * Técnica #12: Pipeline de Composição de Sprite Sheet 4×4 com Isolamento Estrito por Célula (ctx.clip)
+ */
+export declare function renderCompleteSpriteSheet(canvas: HTMLCanvasElement, config: VFXConfig, columns?: number): void;

package/package.json

@@ -1,6 +1,92 @@
 {
   "name": "@sumi-forge/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Japanese Sumi-e (ink wash painting) physics & generative canvas components for React",
+  "author": "Christopher Marques Correa",
+  "license": "Apache-2.0",
+  "keywords": [
+    "react",
+    "sumi-e",
+    "canvas",
+    "brush",
+    "roughjs",
+    "ink-wash",
+    "generative-art",
+    "japanese-calligraphy",
+    "vfx"
+  ],
+  "type": "module",
+  "main": "./dist-lib/index.cjs",
+  "module": "./dist-lib/index.js",
+  "types": "./dist-lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist-lib/index.d.ts",
+      "import": "./dist-lib/index.js",
+      "require": "./dist-lib/index.cjs"
+    }
+  },
+  "files": [
+    "dist-lib",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChristopherMarques/sumiforge.git"
+  },
+  "homepage": "https://sumiforge.vercel.app",
+  "bugs": {
+    "url": "https://github.com/ChristopherMarques/sumiforge/issues"
+  },
+  "scripts": {
+    "dev": "vite --port=3000 --host=0.0.0.0",
+    "clean": "rm -rf dist dist-lib dist-app",
+    "build:types": "tsc -p tsconfig.lib.json",
+    "build:lib": "rm -rf dist-lib && npm run build:types && vite build --config vite.config.lib.ts",
+    "build:app": "vite build",
+    "build": "npm run clean && npm run build:app && npm run build:lib",
+    "preview": "vite preview",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build:lib",
+    "deploy": "npm run build && npm version patch && npm publish --access public"
+  },
+  "dependencies": {
+    "roughjs": "^4.6.6"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@google/genai": "^2.4.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.14.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "autoprefixer": "^10.4.21",
+    "dotenv": "^17.2.3",
+    "esbuild": "^0.25.0",
+    "express": "^4.21.2",
+    "gsap": "^3.15.1",
+    "lucide-react": "^0.546.0",
+    "motion": "^12.23.24",
+    "react": "^19.0.1",
+    "react-dom": "^19.0.1",
+    "tailwindcss": "^4.3.3",
+    "tsx": "^4.21.0",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.0"
+  }
+}