@harpiaresearch/vref 1.0.0 → 1.0.2

package/LICENSE

@@ -1,6 +1,6 @@
 BSD 3-Clause License
 
-Copyright (c) 2024, Harpia AI Research
+Copyright (c) 2026, Harpia AI Research
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

package/README.md

@@ -1,220 +1,274 @@
+<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 (via npx or global/local vref)
+npx @harpiaresearch/vref ./my-images -o references.vref
 
-# With metadata
-npx create-vref ./images -o pack.vref \
+# With metadata (including title name)
+npx @harpiaresearch/vref ./images -o pack.vref \
   -n "My Reference Pack" \
-  -d "Collection of visual references for X" \
-  -t "style,mood,theme" \
+  -d "Collection of art references" \
+  -t "art,style,inspiration" \
   -a "Your Name" \
   -l "CC-BY-4.0"
-
-# From a single image
-npx create-vref image.png -o single.vref
 ```
 
-### 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'],
+  name: 'Art Style References',
+  description: 'Collection of curated art style references',
+  tags: ['art', 'style'],
   author: 'Your Name',
   license: 'CC-BY-4.0',
 });
 
-// Add images from directory
-writer.addImagesFromDirectory('./images', true);
+writer.addImagesFromDirectory('./images');
+writer.write('references.vref');
+```
 
-// Or add individual images
-writer.addImageFromFile('./image1.png');
-writer.addImage('image2.jpg', imageBuffer);
+### Inspecting, Validating & Extracting via CLI
 
-// Write the .vref file
-writer.write('output.vref');
+```bash
+# Inspect metadata and images in a pack
+vref info references.vref
 
-console.log(`Created .vref with ${writer.getImageCount()} images`);
+# Validate format and manifest integrity
+vref validate references.vref
+
+# Extract images to a directory
+vref extract references.vref ./extracted-images
 ```
 
-**Reading a .vref file:**
+### Reading a .vref File
 
 ```typescript
 import { VREFReader } from '@harpiaresearch/vref';
 
-// Read the entire .vref file
-const vref = VREFReader.read('references.vref', { loadImages: true });
+// Read file (optional validation & preloading)
+const vref = VREFReader.read('references.vref', {
+  validate: true,
+  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}`));
-}
+// Extract all images to disk
+VREFReader.extract('references.vref', './extracted');
 ```
 
 ---
 
-## 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",
+  "version": "1.0.2",
   "format": "VREF",
-  "fileName": "my-pack.vref",
+  "fileName": "references.vref",
   "imageCount": 24,
   "images": [
     {
@@ -225,31 +279,47 @@ my-pack.vref (ZIP)
       "height": 1080
     }
   ],
-  "createdAt": "2024-10-12T10:30:00.000Z",
+  "createdAt": "2026-10-13T10:30:00.000Z",
   "metadata": {
-    "description": "Collection of X references",
-    "tags": ["tag1", "tag2"],
-    "author": "Author Name",
+    "name": "RPG Sprites",
+    "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 (`create`, `info`, `validate`, `extract`)
+- ✅ Automated test suite (`node:test`)
+- ✅ Complete documentation
 
-### `VREFWriter`
+### 🇧🇷 Made in Brazil
+Harpia AI Research is putting Brazil on the map of AI innovation.
+
+---
+
+### VREFWriter
 
 ```typescript
 class VREFWriter {
@@ -265,102 +335,100 @@ class VREFWriter {
 }
 ```
 
-### `VREFReader`
+### VREFReader
 
 ```typescript
 class VREFReader {
   static read(filePath: string, options?: VREFReadOptions): VREFReadResult;
   static readManifest(filePath: string): VREFManifest;
   static validate(filePath: string): { valid: boolean; errors: string[] };
+  static extract(filePath: string, targetDir: string): void;
 }
 ```
 
-### 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 (`create`, `info`, `validate`, `extract`)
+- Automated test coverage
+- 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
-
-Copyright (c) 2024, Harpia AI Research
+This project is licensed under the **BSD 3-Clause License** - see the [LICENSE](LICENSE) file for details.
 
-See [LICENSE](LICENSE) for full text.
+Copyright (c) 2026, Harpia AI Research
 
 ---
 
-## 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/dist/VREFReader.d.ts

@@ -19,4 +19,8 @@ export declare class VREFReader {
         valid: boolean;
         errors: string[];
     };
+    /**
+     * Extract all files from a .vref file to a target directory
+     */
+    static extract(filePath: string, targetDir: string): void;
 }

package/dist/VREFReader.js

@@ -51,6 +51,12 @@ class VREFReader {
         if (!fs.existsSync(filePath)) {
             throw new Error(`File not found: ${filePath}`);
         }
+        if (options.validate) {
+            const validation = VREFReader.validate(filePath);
+            if (!validation.valid) {
+                throw new Error(`Invalid .vref file: ${validation.errors.join(', ')}`);
+            }
+        }
         const zip = new adm_zip_1.default(filePath);
         const zipEntries = zip.getEntries();
         // Find and parse manifest
@@ -181,5 +187,18 @@ class VREFReader {
             return { valid: false, errors };
         }
     }
+    /**
+     * Extract all files from a .vref file to a target directory
+     */
+    static extract(filePath, targetDir) {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        if (!fs.existsSync(targetDir)) {
+            fs.mkdirSync(targetDir, { recursive: true });
+        }
+        const zip = new adm_zip_1.default(filePath);
+        zip.extractAllTo(targetDir, true);
+    }
 }
 exports.VREFReader = VREFReader;

package/dist/VREFWriter.d.ts

@@ -32,7 +32,7 @@ export declare class VREFWriter {
      */
     private isValidImageBuffer;
     /**
-     * Get image dimensions (basic implementation for PNG and JPEG)
+     * Get image dimensions (supports PNG, JPEG, GIF, WebP)
      */
     private getImageDimensions;
     /**

package/dist/VREFWriter.js

@@ -125,13 +125,14 @@ class VREFWriter {
         }
         // Create manifest
         const manifest = {
-            version: '1.0.0',
+            version: '1.0.2',
             format: 'VREF',
-            fileName: path.basename(outputPath),
+            fileName: this.options.fileName || path.basename(outputPath),
             imageCount: this.images.size,
             images: imageMetadataList,
             createdAt: new Date().toISOString(),
             metadata: {
+                name: this.options.name,
                 description: this.options.description,
                 tags: this.options.tags,
                 author: this.options.author,
@@ -154,28 +155,56 @@ class VREFWriter {
      * Validate image buffer by checking magic bytes
      */
     isValidImageBuffer(buffer, format) {
-        if (buffer.length < 8)
+        if (!buffer || buffer.length < 8)
             return false;
         switch (format.toLowerCase()) {
             case 'png':
-                return buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47;
+                return (buffer.length >= 8 &&
+                    buffer[0] === 0x89 &&
+                    buffer[1] === 0x50 &&
+                    buffer[2] === 0x4e &&
+                    buffer[3] === 0x47);
             case 'jpg':
             case 'jpeg':
-                return buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff;
+                return (buffer.length >= 3 &&
+                    buffer[0] === 0xff &&
+                    buffer[1] === 0xd8 &&
+                    buffer[2] === 0xff);
             case 'gif':
-                return buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46;
+                return (buffer.length >= 6 &&
+                    buffer[0] === 0x47 &&
+                    buffer[1] === 0x49 &&
+                    buffer[2] === 0x46 &&
+                    buffer[3] === 0x38 &&
+                    (buffer[4] === 0x37 || buffer[4] === 0x39) &&
+                    buffer[5] === 0x61);
             case 'webp':
-                return buffer[8] === 0x57 && buffer[9] === 0x45 && buffer[10] === 0x42 && buffer[11] === 0x50;
+                return (buffer.length >= 12 &&
+                    buffer[0] === 0x52 &&
+                    buffer[1] === 0x49 &&
+                    buffer[2] === 0x46 &&
+                    buffer[3] === 0x46 &&
+                    buffer[8] === 0x57 &&
+                    buffer[9] === 0x45 &&
+                    buffer[10] === 0x42 &&
+                    buffer[11] === 0x50);
             case 'avif':
-                // AVIF detection is more complex, but we can check for 'ftyp' box
-                const ftypCheck = buffer.toString('ascii', 4, 8);
-                return ftypCheck === 'ftyp';
+                if (buffer.length < 16)
+                    return false;
+                const ftypBox = buffer.toString('ascii', 4, 8);
+                if (ftypBox !== 'ftyp')
+                    return false;
+                const majorBrand = buffer.toString('ascii', 8, 12);
+                if (majorBrand === 'avif' || majorBrand === 'avis')
+                    return true;
+                const headerSlice = buffer.subarray(12, Math.min(buffer.length, 64)).toString('ascii');
+                return headerSlice.includes('avif') || headerSlice.includes('avis');
             default:
                 return false;
         }
     }
     /**
-     * Get image dimensions (basic implementation for PNG and JPEG)
+     * Get image dimensions (supports PNG, JPEG, GIF, WebP)
      */
     getImageDimensions(buffer, format) {
         try {
@@ -185,8 +214,6 @@ class VREFWriter {
                 return { width, height };
             }
             if ((format === 'jpg' || format === 'jpeg') && buffer.length >= 4) {
-                // Basic JPEG dimension extraction (simplified)
-                // This is a simplified version; production code might use a library
                 let offset = 2;
                 while (offset < buffer.length) {
                     if (buffer[offset] !== 0xff)
@@ -202,6 +229,33 @@ class VREFWriter {
                     offset += segmentLength;
                 }
             }
+            if (format === 'gif' && buffer.length >= 10) {
+                const width = buffer.readUInt16LE(6);
+                const height = buffer.readUInt16LE(8);
+                return { width, height };
+            }
+            if (format === 'webp' && buffer.length >= 30) {
+                const chunkType = buffer.toString('ascii', 12, 16);
+                if (chunkType === 'VP8 ' && buffer.length >= 30) {
+                    const width = buffer.readUInt16LE(26) & 0x3fff;
+                    const height = buffer.readUInt16LE(28) & 0x3fff;
+                    return { width, height };
+                }
+                else if (chunkType === 'VP8L' && buffer.length >= 25) {
+                    const b1 = buffer[21];
+                    const b2 = buffer[22];
+                    const b3 = buffer[23];
+                    const b4 = buffer[24];
+                    const width = 1 + (((b2 & 0x3f) << 8) | b1);
+                    const height = 1 + (((b4 & 0x0f) << 10) | (b3 << 2) | ((b2 & 0xc0) >> 6));
+                    return { width, height };
+                }
+                else if (chunkType === 'VP8X' && buffer.length >= 30) {
+                    const width = 1 + buffer.readUIntLE(24, 3);
+                    const height = 1 + buffer.readUIntLE(27, 3);
+                    return { width, height };
+                }
+            }
         }
         catch (error) {
             // If dimension extraction fails, just return undefined

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * VREF CLI - Command line interface for creating .vref files
+ * VREF CLI - Command line interface for .vref files
  * Harpia AI Research
  */
 export {};

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 /**
- * VREF CLI - Command line interface for creating .vref files
+ * VREF CLI - Command line interface for .vref files
  * Harpia AI Research
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
@@ -41,47 +41,144 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const VREFWriter_1 = require("./VREFWriter");
+const VREFReader_1 = require("./VREFReader");
+const CLI_VERSION = '1.0.2';
 function showHelp() {
     console.log(`
 ┌─────────────────────────────────────────────────┐
-│  VREF CLI v1.0.0                                │
+│  VREF CLI v${CLI_VERSION}                                │
 │  by Harpia AI Research                          │
 │  https://harpiaresearch.cc                      │
 └─────────────────────────────────────────────────┘
 
-Create .vref files from images
+Standardized container for curated visual references in AI image generation
 
 USAGE:
-  npx create-vref <input> [options]
-  
-ARGUMENTS:
-  <input>              Path to image file or directory
+  npx @harpiaresearch/vref <input> [options]
+  vref <command> [arguments]
 
-OPTIONS:
-  -o, --output <path>  Output .vref file path (default: output.vref)
-  -n, --name <name>    Name for the reference pack
-  -d, --desc <text>    Description of the reference pack
-  -t, --tags <tags>    Comma-separated tags
-  -a, --author <name>  Author name
-  -l, --license <lic>  License (e.g., CC-BY-4.0, MIT)
-  -r, --recursive      Include subdirectories
-  -h, --help           Show this help
+COMMANDS:
+  <input> [options]          Create a .vref file from an image or directory
+  info, inspect <file.vref>  Inspect metadata and images in a .vref file
+  validate <file.vref>       Validate integrity and manifest of a .vref file
+  extract <file.vref> [dir]  Extract all images from a .vref file
+
+CREATION OPTIONS:
+  -o, --output <path>   Output .vref file path (default: output.vref)
+  -n, --name <name>     Name/title for the reference pack
+  -d, --desc <text>     Description of the reference pack
+  -t, --tags <tags>     Comma-separated tags
+  -a, --author <name>   Author name
+  -l, --license <lic>   License (e.g., CC-BY-4.0, MIT)
+  -r, --recursive       Include subdirectories
+  -v, --version         Show CLI version
+  -h, --help            Show this help
 
 EXAMPLES:
-  # Create from single image
-  npx create-vref image.png -o references.vref
-  
   # Create from directory
-  npx create-vref ./images -o pack.vref -n "My Pack"
-  
-  # With metadata
-  npx create-vref ./sprites -o rpg-sprites.vref \\
+  npx @harpiaresearch/vref ./images -o pack.vref -n "My Pack"
+
+  # Create with complete metadata
+  npx @harpiaresearch/vref ./sprites -o rpg-sprites.vref \\
     -n "RPG Sprites" \\
     -d "Character sprites for RPG games" \\
     -t "rpg,sprites,pixelart" \\
     -a "Your Name" \\
     -l "CC-BY-4.0"
-  `);
+
+  # Inspect an existing .vref file
+  vref info references.vref
+
+  # Validate file integrity
+  vref validate references.vref
+
+  # Extract images
+  vref extract references.vref ./extracted-images
+`);
+}
+function handleValidate(filePath) {
+    if (!filePath) {
+        console.error('❌ Error: Please specify a .vref file to validate');
+        process.exit(1);
+    }
+    console.log(`🔍 Validating ${filePath}...`);
+    const result = VREFReader_1.VREFReader.validate(filePath);
+    if (result.valid) {
+        const manifest = VREFReader_1.VREFReader.readManifest(filePath);
+        console.log(`✅ Valid .vref file!`);
+        console.log(`   Format: ${manifest.format} (v${manifest.version})`);
+        console.log(`   Images: ${manifest.imageCount}`);
+        if (manifest.metadata?.name)
+            console.log(`   Name: ${manifest.metadata.name}`);
+    }
+    else {
+        console.error(`❌ Validation failed with ${result.errors.length} error(s):`);
+        result.errors.forEach(err => console.error(`   - ${err}`));
+        process.exit(1);
+    }
+}
+function handleInfo(filePath) {
+    if (!filePath) {
+        console.error('❌ Error: Please specify a .vref file to inspect');
+        process.exit(1);
+    }
+    try {
+        const manifest = VREFReader_1.VREFReader.readManifest(filePath);
+        const stats = fs.statSync(filePath);
+        const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+        console.log(`\n📦 File: ${path.basename(filePath)} (${sizeMB} MB)`);
+        console.log(`   Format: ${manifest.format} v${manifest.version}`);
+        console.log(`   Created at: ${manifest.createdAt}`);
+        console.log(`   Total images: ${manifest.imageCount}`);
+        if (manifest.metadata) {
+            console.log('\n📋 Metadata:');
+            if (manifest.metadata.name)
+                console.log(`   Name: ${manifest.metadata.name}`);
+            if (manifest.metadata.description)
+                console.log(`   Description: ${manifest.metadata.description}`);
+            if (manifest.metadata.tags && manifest.metadata.tags.length > 0) {
+                console.log(`   Tags: ${manifest.metadata.tags.join(', ')}`);
+            }
+            if (manifest.metadata.author)
+                console.log(`   Author: ${manifest.metadata.author}`);
+            if (manifest.metadata.license)
+                console.log(`   License: ${manifest.metadata.license}`);
+        }
+        if (manifest.images.length > 0) {
+            console.log('\n🖼️ Sample of contained images:');
+            const previewCount = Math.min(manifest.images.length, 5);
+            for (let i = 0; i < previewCount; i++) {
+                const img = manifest.images[i];
+                const dim = img.width && img.height ? ` (${img.width}x${img.height})` : '';
+                const sizeKB = (img.size / 1024).toFixed(1);
+                console.log(`   - ${img.path} [${img.format.toUpperCase()}]${dim} - ${sizeKB} KB`);
+            }
+            if (manifest.images.length > previewCount) {
+                console.log(`   ... and ${manifest.images.length - previewCount} more`);
+            }
+        }
+        console.log();
+    }
+    catch (error) {
+        console.error(`❌ Error inspecting file: ${error.message}`);
+        process.exit(1);
+    }
+}
+function handleExtract(filePath, outputDir) {
+    if (!filePath) {
+        console.error('❌ Error: Please specify a .vref file to extract');
+        process.exit(1);
+    }
+    const targetDir = outputDir || path.join(process.cwd(), path.basename(filePath, '.vref') + '_extracted');
+    try {
+        console.log(`📦 Extracting ${filePath} to ${targetDir}...`);
+        VREFReader_1.VREFReader.extract(filePath, targetDir);
+        console.log(`✅ Extracted successfully to ${targetDir}`);
+    }
+    catch (error) {
+        console.error(`❌ Extraction error: ${error.message}`);
+        process.exit(1);
+    }
 }
 function parseArgs(args) {
     const options = {
@@ -102,6 +199,11 @@ function parseArgs(args) {
                 showHelp();
                 process.exit(0);
                 break;
+            case '-v':
+            case '--version':
+                console.log(`v${CLI_VERSION}`);
+                process.exit(0);
+                break;
             case '-o':
             case '--output':
                 options.output = args[++i];
@@ -117,7 +219,7 @@ function parseArgs(args) {
                 break;
             case '-t':
             case '--tags':
-                options.tags = args[++i].split(',').map((t) => t.trim());
+                options.tags = args[++i]?.split(',').map((t) => t.trim());
                 break;
             case '-a':
             case '--author':
@@ -132,7 +234,7 @@ function parseArgs(args) {
                 options.recursive = true;
                 break;
             default:
-                if (!arg.startsWith('-')) {
+                if (!arg.startsWith('-') && !options.input) {
                     options.input = arg;
                 }
                 break;
@@ -146,10 +248,31 @@ function main() {
         showHelp();
         process.exit(0);
     }
+    const firstArg = args[0];
+    if (firstArg === 'validate') {
+        handleValidate(args[1]);
+        return;
+    }
+    if (firstArg === 'info' || firstArg === 'inspect') {
+        handleInfo(args[1]);
+        return;
+    }
+    if (firstArg === 'extract') {
+        handleExtract(args[1], args[2]);
+        return;
+    }
+    if (firstArg === '-h' || firstArg === '--help') {
+        showHelp();
+        process.exit(0);
+    }
+    if (firstArg === '-v' || firstArg === '--version') {
+        console.log(`v${CLI_VERSION}`);
+        process.exit(0);
+    }
     const options = parseArgs(args);
     if (!options.input) {
         console.error('❌ Error: No input specified');
-        console.log('Run "npx create-vref --help" for usage information');
+        console.log('Run "npx @harpiaresearch/vref --help" for usage information');
         process.exit(1);
     }
     if (!fs.existsSync(options.input)) {
@@ -157,13 +280,13 @@ function main() {
         process.exit(1);
     }
     console.log('┌─────────────────────────────────────────────────┐');
-    console.log('│  VREF CLI v1.0.0                                │');
+    console.log(`│  VREF CLI v${CLI_VERSION}                                │`);
     console.log('│  by Harpia AI Research                          │');
     console.log('└─────────────────────────────────────────────────┘\n');
     try {
-        const fileName = options.name || path.basename(options.output, '.vref');
         const writer = new VREFWriter_1.VREFWriter({
-            fileName: options.output,
+            fileName: path.basename(options.output),
+            name: options.name,
             description: options.description,
             tags: options.tags,
             author: options.author,

package/dist/types.d.ts

@@ -23,6 +23,8 @@ export interface VREFManifest {
     createdAt: string;
     /** Optional metadata */
     metadata?: {
+        /** Human-readable title/name of the reference pack */
+        name?: string;
         /** Description of the reference pack */
         description?: string;
         /** Tags for categorization */
@@ -54,8 +56,10 @@ export interface ImageMetadata {
  * Options for creating a VREF file
  */
 export interface VREFCreateOptions {
-    /** Name for the output .vref file */
-    fileName: string;
+    /** Optional name/title for the reference pack */
+    name?: string;
+    /** Name for the output .vref file (optional, defaults to output path file name) */
+    fileName?: string;
     /** Optional description */
     description?: string;
     /** Optional tags */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harpiaresearch/vref",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Visual Reference Format - Standardized container for curated visual references in AI image generation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,8 +10,8 @@
     "LICENSE"
   ],
   "bin": {
-    "create-vref": "./dist/cli.js",
-    "vref": "./dist/cli.js"
+    "create-vref": "dist/cli.js",
+    "vref": "dist/cli.js"
   },
   "scripts": {
     "build": "tsc",
@@ -32,7 +32,7 @@
   "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Harpia-AI-Research/vref"
+    "url": "git+https://github.com/Harpia-AI-Research/vref.git"
   },
   "dependencies": {
     "adm-zip": "^0.5.10"