@harpiaresearch/vref 1.0.0 → 1.0.1

package/README.md

@@ -1,220 +1,251 @@
+<div align="center">
+
 # VREF — Visual Reference Format
 
-> **Standardized container for curated visual references in AI image generation**
+**A standardized format for curated visual references in AI image generation**
 
 [![npm version](https://img.shields.io/npm/v/@harpiaresearch/vref)](https://www.npmjs.com/package/@harpiaresearch/vref)
 [![License](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](LICENSE)
 
-Developed by [Harpia AI Research](https://harpiaresearch.cc) 🇧🇷
+Harpia AI Research
+
+</div>
+
+---
+
+<div align="center">
+
+## The Problem
+
+</div>
+
+You know exactly what you want your AI to generate, but describing it in words is **nearly impossible**.
+
+- 🤔 "How do I describe this art style?"
+- 📸 "I have 20 reference images, but uploading them one by one is tedious"
+- 🔄 "I can't easily share or reuse my reference collections"
+- 😤 "Text prompts alone just don't capture the vision"
+
+**Visual concepts are hard to describe, but easy to show.**
+
+---
+
+<div align="center">
+
+## The Solution
+
+**VREF** (Visual Reference Format) is a simple, open standard that packages your visual references into a single `.vref` file.
+
+```
+Your 50 reference images → one references.vref file
+```
+
+</div>
+
+### How It Works
+
+```
+1. Package images → references.vref
+2. Upload to AI platform
+3. Platform samples N random images
+4. You write text prompt
+5. AI generates with visual context
+```
+
+Instead of fighting with text descriptions, you **show the AI what you want**.
 
 ---
 
-## What is VREF?
+<div align="center">
+
+## Why You Should Use VREF
 
-VREF (Visual Reference Format) is an open standard for packaging and sharing curated visual references for AI image generation platforms.
+</div>
 
-Instead of uploading multiple loose images or struggling to describe complex visual concepts in text, users can:
+### ✅ For Creators
 
-1. **Package** reference images into a single `.vref` file
-2. **Upload** the `.vref` to any supporting AI platform
-3. **Select** how many random references to use (via slider)
-4. **Generate** images with visual context
+**Stop struggling with prompts.**
+- Package your mood boards, style references, and inspirations
+- Upload once, reuse forever
+- Share with your team or community
 
-### The Problem
+**Example:** Download `roblox-banners.vref` → Upload → Describe what you want → Get perfect results
 
-When generating images with AI, users often:
-- ❌ Know what they want visually but can't describe it in words
-- ❌ Need to upload 10-50 reference images individually
-- ❌ Can't easily share or reuse reference collections
-- ❌ Struggle to communicate style, mood, and composition
+### ✅ For Platforms
 
-### The Solution
+**Better user experience.**
+- Users get better results faster
+- Reduces prompt engineering frustration
+- Differentiates your platform
+- Simple to implement (< 1 day)
 
-VREF provides:
-- ✅ **Single file** container for multiple images
-- ✅ **Validated** image-only format
-- ✅ **Structured metadata** (tags, description, license)
-- ✅ **Portable** and shareable
-- ✅ **Random sampling** built-in
-- ✅ **Open standard** anyone can implement
+### ✅ For Everyone
+
+**It's an open standard.**
+- No vendor lock-in
+- Portable across platforms
+- Community-driven
+- Free forever
 
 ---
 
+<div align="center">
+
+## Real-World Use Cases
+
+</div>
+
+### 🎮 Game Development
+```
+rpg-sprites.vref      → Character references
+platformer-tiles.vref → Level design inspiration
+ui-elements.vref      → Interface styles
+```
+
+### 🎨 Creative Work
+```
+architecture.vref     → Building styles
+color-palettes.vref   → Mood and tone
+typography.vref       → Font and layout ideas
+```
+
+### 🤖 AI Training
+```
+training-data.vref    → Curated datasets
+style-transfer.vref   → Style references
+fine-tuning.vref      → Model-specific data
+```
+
+---
+
+<div align="center">
+
 ## Installation
 
+</div>
+
 ```bash
 npm install @harpiaresearch/vref
 ```
 
-Or use directly with `npx`:
+Or use directly:
 
 ```bash
-npx create-vref
+npx @harpiaresearch/vref
 ```
 
 ---
 
+<div align="center">
+
 ## Quick Start
 
-### Creating a .vref file (CLI)
+</div>
+
+### Creating a .vref File
 
+**CLI:**
 ```bash
-# From a directory of images
-npx create-vref ./my-images -o references.vref
+# From a directory
+npx @harpiaresearch/vref ./my-images -o references.vref
 
 # With metadata
-npx create-vref ./images -o pack.vref \
+npx @harpiaresearch/vref ./images -o pack.vref \
   -n "My Reference Pack" \
-  -d "Collection of visual references for X" \
-  -t "style,mood,theme" \
-  -a "Your Name" \
-  -l "CC-BY-4.0"
-
-# From a single image
-npx create-vref image.png -o single.vref
+  -d "Collection of art references" \
+  -t "art,style,inspiration"
 ```
 
-### Using the library (JavaScript/TypeScript)
-
-**Creating a .vref file:**
-
+**Code:**
 ```typescript
 import { VREFWriter } from '@harpiaresearch/vref';
 
 const writer = new VREFWriter({
-  fileName: 'my-pack.vref',
-  description: 'Collection of RPG character references',
-  tags: ['rpg', 'characters', 'fantasy'],
-  author: 'Your Name',
-  license: 'CC-BY-4.0',
+  fileName: 'references.vref',
+  description: 'Art style references',
+  tags: ['art', 'style'],
 });
 
-// Add images from directory
-writer.addImagesFromDirectory('./images', true);
-
-// Or add individual images
-writer.addImageFromFile('./image1.png');
-writer.addImage('image2.jpg', imageBuffer);
-
-// Write the .vref file
-writer.write('output.vref');
-
-console.log(`Created .vref with ${writer.getImageCount()} images`);
+writer.addImagesFromDirectory('./images');
+writer.write('references.vref');
 ```
 
-**Reading a .vref file:**
+### Reading a .vref File
 
 ```typescript
 import { VREFReader } from '@harpiaresearch/vref';
 
-// Read the entire .vref file
+// Read file
 const vref = VREFReader.read('references.vref', { loadImages: true });
 
 console.log(`Loaded ${vref.manifest.imageCount} images`);
-console.log(`Description: ${vref.manifest.metadata?.description}`);
 
-// Get random sample of 3 images
-const randomImages = vref.sample(3);
-randomImages.forEach((buffer, idx) => {
-  console.log(`Image ${idx + 1}: ${buffer.length} bytes`);
-});
+// Sample 3 random images
+const randomSamples = vref.sample(3);
 
 // Get specific image
 const image = vref.getImage('photo1.png');
-if (image) {
-  // Do something with the image buffer
-}
-```
-
-**Read only the manifest:**
-
-```typescript
-import { VREFReader } from '@harpiaresearch/vref';
-
-const manifest = VREFReader.readManifest('references.vref');
-console.log(manifest);
-```
-
-**Validate a .vref file:**
-
-```typescript
-import { VREFReader } from '@harpiaresearch/vref';
-
-const result = VREFReader.validate('references.vref');
-if (result.valid) {
-  console.log('✅ Valid .vref file');
-} else {
-  console.error('❌ Invalid .vref file:');
-  result.errors.forEach(err => console.error(`  - ${err}`));
-}
 ```
 
 ---
 
-## Use Cases
-
-### 1. **AI Image Generation Platforms**
+<div align="center">
 
-Users upload `.vref` files to platforms like:
-- Midjourney
-- Stable Diffusion
-- DALL-E
-- Replicate
-- Custom AI platforms
+## For AI Platform Developers
 
-The platform extracts random images and sends them as visual context along with the user's text prompt.
+Integrating VREF takes **< 1 day**:
 
-### 2. **Game Development**
+</div>
 
-Distribute reference packs:
-- `rpg-sprites.vref` — Character sprites for RPG games
-- `platformer-tiles.vref` — Tile sets for platformers
-- `ui-elements.vref` — UI design references
+```typescript
+import { VREFReader } from '@harpiaresearch/vref';
 
-### 3. **Training ML Models**
+// 1. User uploads .vref
+const vref = VREFReader.read(uploadedFile, { loadImages: true });
 
-Use `.vref` files as datasets:
+// 2. Show slider: "How many references? (1-{imageCount})"
+const count = getUserSliderValue();
 
-```typescript
-import { VREFReader } from '@harpiaresearch/vref';
-import { PixelGenModel } from '@harpiaresearch/pixelgen';
+// 3. Sample random images
+const references = vref.sample(count);
 
-const dataset = VREFReader.read('training-data.vref', { loadImages: true });
-const model = new PixelGenModel(3, 3);
+// 4. Get user prompt
+const prompt = getUserPrompt();
 
-// Train with VREF data
-// ...
+// 5. Send to your AI
+await generateImage({
+  prompt: prompt,
+  referenceImages: references,
+});
 ```
 
-### 4. **Design & Creative Work**
-
-Share mood boards and references:
-- `architecture-modern.vref`
-- `color-palettes-warm.vref`
-- `typography-references.vref`
+**That's it.** ✅
 
 ---
 
-## File Format Specification
+## File Format
 
 A `.vref` file is a ZIP container with:
 
 ```
-my-pack.vref (ZIP)
-├── manifest.json
+references.vref
+├── manifest.json    (metadata)
 ├── image1.png
 ├── image2.jpg
-├── image3.webp
-└── ...
+└── image3.webp
 ```
 
-### `manifest.json` Structure
+**Supported formats:** PNG, JPEG, WebP, GIF, AVIF
+
+**Only images allowed.** Any other file type is rejected.
+
+### manifest.json
 
 ```json
 {
   "version": "1.0.0",
   "format": "VREF",
-  "fileName": "my-pack.vref",
+  "fileName": "references.vref",
   "imageCount": 24,
   "images": [
     {
@@ -227,29 +258,43 @@ my-pack.vref (ZIP)
   ],
   "createdAt": "2024-10-12T10:30:00.000Z",
   "metadata": {
-    "description": "Collection of X references",
-    "tags": ["tag1", "tag2"],
-    "author": "Author Name",
+    "description": "Collection of references",
+    "tags": ["style", "mood"],
+    "author": "Your Name",
     "license": "CC-BY-4.0"
   }
 }
 ```
 
-### Supported Image Formats
+---
 
-- ✅ PNG (`.png`)
-- ✅ JPEG (`.jpg`, `.jpeg`)
-- ✅ WebP (`.webp`)
-- ✅ GIF (`.gif`)
-- ✅ AVIF (`.avif`)
+<div align="center">
 
-Any other file type is **rejected** with an error.
+## Why VREF Will Win
 
----
+</div>
+
+### 🎯 Solves a Real Problem
+Everyone who uses AI image generation has struggled with describing visual concepts. VREF makes it trivial.
+
+### 🚀 Simple to Implement
+ZIP + JSON. No complex dependencies. Works everywhere.
+
+### 🌍 Open Standard
+No company owns it. Community-driven. Free forever.
 
-## API Reference
+### 📦 Already Shipping
+- ✅ npm package published
+- ✅ Full TypeScript support
+- ✅ CLI tool ready
+- ✅ Documentation complete
 
-### `VREFWriter`
+### 🇧🇷 Made in Brazil
+Harpia AI Research is putting Brazil on the map of AI innovation.
+
+---
+
+### VREFWriter
 
 ```typescript
 class VREFWriter {
@@ -261,11 +306,10 @@ class VREFWriter {
   
   write(outputPath: string): void;
   getImageCount(): number;
-  clear(): void;
 }
 ```
 
-### `VREFReader`
+### VREFReader
 
 ```typescript
 class VREFReader {
@@ -275,92 +319,88 @@ class VREFReader {
 }
 ```
 
-### Types
-
-See [src/types.ts](src/types.ts) for complete type definitions.
-
----
-
-## Platform Integration
-
-### For AI Platform Developers
-
-Integrating VREF support:
+### VREFReadResult
 
 ```typescript
-import { VREFReader } from '@harpiaresearch/vref';
+interface VREFReadResult {
+  manifest: VREFManifest;
+  images?: Map<string, Buffer>;
+  sample: (count: number) => Buffer[];
+  getImage: (path: string) => Buffer | undefined;
+}
+```
 
-// 1. User uploads .vref file
-const vref = VREFReader.read(uploadedFile, { loadImages: true });
+Full API documentation: [TypeScript definitions](src/types.ts)
 
-// 2. Show slider: "How many references? (1 - {vref.manifest.imageCount})"
-const userSelectedCount = getUserSliderValue(); // e.g., 3
+---
 
-// 3. Sample random images
-const selectedImages = vref.sample(userSelectedCount);
+## Roadmap
 
-// 4. Get user's text prompt
-const userPrompt = getUserPrompt(); // "A warrior character in pixel art style"
+### Phase 1 ✅ (Done)
+- Core library implementation
+- CLI tool
+- npm package published
+- Full documentation
 
-// 5. Send to your AI model
-await generateImage({
-  prompt: userPrompt,
-  referenceImages: selectedImages,
-});
-```
+### Phase 2 (In Progress)
+- Community-created .vref files
+- Platform integrations
+- Example collections
 
-That's it! 🎉
+### Phase 3 (Future)
+- Web-based .vref creator
+- .vref marketplace
+- Browser extensions
+- Mobile support
 
 ---
 
-## Examples
+## Join the Movement
 
-See the [examples/](examples/) directory for:
-- Creating `.vref` files
-- Reading and sampling images
-- Platform integration examples
-- PixelGen integration
+VREF is just getting started. We need:
+
+- **Platform developers**: Integrate VREF support
+- **Creators**: Build and share .vref collections
+- **Contributors**: Improve the library
+- **Evangelists**: Spread the word
 
 ---
 
-## Contributing
+## Links
 
-We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+- **npm**: https://www.npmjs.com/package/@harpiaresearch/vref
+- **GitHub**: https://github.com/Harpia-AI-Research/vref
+- **Harpia AI Research**: https://harpiaresearch.cc
+- **Issues**: https://github.com/Harpia-AI-Research/vref/issues
 
 ---
 
 ## License
 
-BSD 3-Clause License
+This project is licensed under the **BSD 3-Clause License** - see the [LICENSE](LICENSE) file for details.
 
 Copyright (c) 2024, Harpia AI Research
 
-See [LICENSE](LICENSE) for full text.
-
 ---
 
-## Citation
+## Acknowledgments
 
-If you use VREF in your research or project:
+VREF is an open standard for visual references in AI systems. Built to solve the gap between what creators envision and what they can describe in text.
 
-```bibtex
-@software{vref2024,
-  title = {VREF: Visual Reference Format for AI Image Generation},
-  author = {Harpia AI Research},
-  year = {2024},
-  url = {https://github.com/Harpia-AI-Research/vref}
-}
-```
+**Technologies**: TypeScript, Node.js, adm-zip
 
 ---
 
-## Links
+<div align="center">
 
-- 🌐 Website: [harpiaresearch.cc](https://harpiaresearch.cc)
-- 📦 npm: [@harpiaresearch/vref](https://www.npmjs.com/package/@harpiaresearch/vref)
-- 📄 Specification: [docs/SPECIFICATION.md](docs/SPECIFICATION.md)
-- 💬 Issues: [GitHub Issues](https://github.com/Harpia-AI-Research/vref/issues)
+**VREF** — Bridging vision and AI generation
 
----
+<br><br>
+
+[GitHub](https://github.com/Harpia-AI-Research/vref) •
+[npm](https://www.npmjs.com/package/@harpiaresearch/vref) •
+[Documentation](https://github.com/Harpia-AI-Research/vref#readme) •
+[Issues](https://github.com/Harpia-AI-Research/vref/issues)
+
+</div>
 
-**Made with 💚💛 by Harpia AI Research — São Paulo, Brazil** 🇧🇷

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harpiaresearch/vref",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Visual Reference Format - Standardized container for curated visual references in AI image generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",