@harpiaresearch/vref 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2024, Harpia AI Research
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,406 @@
-# Temporary Holding Version
+<div align="center">
+
+# VREF — Visual Reference Format
+
+**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)
+
+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**.
+
+---
+
+<div align="center">
+
+## Why You Should Use VREF
+
+</div>
+
+### ✅ For Creators
+
+**Stop struggling with prompts.**
+- Package your mood boards, style references, and inspirations
+- Upload once, reuse forever
+- Share with your team or community
+
+**Example:** Download `roblox-banners.vref` → Upload → Describe what you want → Get perfect results
+
+### ✅ For Platforms
+
+**Better user experience.**
+- Users get better results faster
+- Reduces prompt engineering frustration
+- Differentiates your platform
+- Simple to implement (< 1 day)
+
+### ✅ 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:
+
+```bash
+npx @harpiaresearch/vref
+```
+
+---
+
+<div align="center">
+
+## Quick Start
+
+</div>
+
+### Creating a .vref File
+
+**CLI:**
+```bash
+# From a directory
+npx @harpiaresearch/vref ./my-images -o references.vref
+
+# With metadata
+npx @harpiaresearch/vref ./images -o pack.vref \
+  -n "My Reference Pack" \
+  -d "Collection of art references" \
+  -t "art,style,inspiration"
+```
+
+**Code:**
+```typescript
+import { VREFWriter } from '@harpiaresearch/vref';
+
+const writer = new VREFWriter({
+  fileName: 'references.vref',
+  description: 'Art style references',
+  tags: ['art', 'style'],
+});
+
+writer.addImagesFromDirectory('./images');
+writer.write('references.vref');
+```
+
+### Reading a .vref File
+
+```typescript
+import { VREFReader } from '@harpiaresearch/vref';
+
+// Read file
+const vref = VREFReader.read('references.vref', { loadImages: true });
+
+console.log(`Loaded ${vref.manifest.imageCount} images`);
+
+// Sample 3 random images
+const randomSamples = vref.sample(3);
+
+// Get specific image
+const image = vref.getImage('photo1.png');
+```
+
+---
+
+<div align="center">
+
+## For AI Platform Developers
+
+Integrating VREF takes **< 1 day**:
+
+</div>
+
+```typescript
+import { VREFReader } from '@harpiaresearch/vref';
+
+// 1. User uploads .vref
+const vref = VREFReader.read(uploadedFile, { loadImages: true });
+
+// 2. Show slider: "How many references? (1-{imageCount})"
+const count = getUserSliderValue();
+
+// 3. Sample random images
+const references = vref.sample(count);
+
+// 4. Get user prompt
+const prompt = getUserPrompt();
+
+// 5. Send to your AI
+await generateImage({
+  prompt: prompt,
+  referenceImages: references,
+});
+```
+
+**That's it.** ✅
+
+---
+
+## File Format
+
+A `.vref` file is a ZIP container with:
+
+```
+references.vref
+├── manifest.json    (metadata)
+├── image1.png
+├── image2.jpg
+└── image3.webp
+```
+
+**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": "references.vref",
+  "imageCount": 24,
+  "images": [
+    {
+      "path": "image1.png",
+      "format": "png",
+      "size": 45678,
+      "width": 1920,
+      "height": 1080
+    }
+  ],
+  "createdAt": "2024-10-12T10:30:00.000Z",
+  "metadata": {
+    "description": "Collection of references",
+    "tags": ["style", "mood"],
+    "author": "Your Name",
+    "license": "CC-BY-4.0"
+  }
+}
+```
+
+---
+
+<div align="center">
+
+## 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.
+
+### 📦 Already Shipping
+- ✅ npm package published
+- ✅ Full TypeScript support
+- ✅ CLI tool ready
+- ✅ Documentation complete
+
+### 🇧🇷 Made in Brazil
+Harpia AI Research is putting Brazil on the map of AI innovation.
+
+---
+
+### VREFWriter
+
+```typescript
+class VREFWriter {
+  constructor(options: VREFCreateOptions);
+  
+  addImageFromFile(filePath: string): void;
+  addImage(fileName: string, buffer: Buffer): void;
+  addImagesFromDirectory(dirPath: string, recursive?: boolean): void;
+  
+  write(outputPath: string): void;
+  getImageCount(): number;
+}
+```
+
+### VREFReader
+
+```typescript
+class VREFReader {
+  static read(filePath: string, options?: VREFReadOptions): VREFReadResult;
+  static readManifest(filePath: string): VREFManifest;
+  static validate(filePath: string): { valid: boolean; errors: string[] };
+}
+```
+
+### VREFReadResult
+
+```typescript
+interface VREFReadResult {
+  manifest: VREFManifest;
+  images?: Map<string, Buffer>;
+  sample: (count: number) => Buffer[];
+  getImage: (path: string) => Buffer | undefined;
+}
+```
+
+Full API documentation: [TypeScript definitions](src/types.ts)
+
+---
+
+## Roadmap
+
+### Phase 1 ✅ (Done)
+- Core library implementation
+- CLI tool
+- npm package published
+- Full documentation
+
+### Phase 2 (In Progress)
+- Community-created .vref files
+- Platform integrations
+- Example collections
+
+### Phase 3 (Future)
+- Web-based .vref creator
+- .vref marketplace
+- Browser extensions
+- Mobile support
+
+---
+
+## Join the Movement
+
+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
+
+---
+
+## Links
+
+- **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
+
+This project is licensed under the **BSD 3-Clause License** - see the [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2024, Harpia AI Research
+
+---
+
+## Acknowledgments
+
+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.
+
+**Technologies**: TypeScript, Node.js, adm-zip
+
+---
+
+<div align="center">
+
+**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>
 
-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.

package/dist/VREFReader.d.ts

@@ -0,0 +1,22 @@
+/**
+ * VREFReader - Reads .vref files
+ * Harpia AI Research
+ */
+import { VREFManifest, VREFReadOptions, VREFReadResult } from './types';
+export declare class VREFReader {
+    /**
+     * Read a .vref file
+     */
+    static read(filePath: string, options?: VREFReadOptions): VREFReadResult;
+    /**
+     * Read only the manifest without loading images
+     */
+    static readManifest(filePath: string): VREFManifest;
+    /**
+     * Validate a .vref file
+     */
+    static validate(filePath: string): {
+        valid: boolean;
+        errors: string[];
+    };
+}

package/dist/VREFReader.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * VREFReader - Reads .vref files
+ * Harpia AI Research
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VREFReader = void 0;
+const fs = __importStar(require("fs"));
+const adm_zip_1 = __importDefault(require("adm-zip"));
+class VREFReader {
+    /**
+     * Read a .vref file
+     */
+    static read(filePath, options = {}) {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        const zip = new adm_zip_1.default(filePath);
+        const zipEntries = zip.getEntries();
+        // Find and parse manifest
+        const manifestEntry = zipEntries.find(entry => entry.entryName === 'manifest.json');
+        if (!manifestEntry) {
+            throw new Error('Invalid .vref file: manifest.json not found');
+        }
+        const manifestData = manifestEntry.getData().toString('utf8');
+        const manifest = JSON.parse(manifestData);
+        // Validate manifest
+        if (manifest.format !== 'VREF') {
+            throw new Error('Invalid .vref file: incorrect format identifier');
+        }
+        // Load images if requested
+        const images = new Map();
+        if (options.loadImages) {
+            for (const imageInfo of manifest.images) {
+                const entry = zipEntries.find(e => e.entryName === imageInfo.path);
+                if (entry) {
+                    images.set(imageInfo.path, entry.getData());
+                }
+            }
+        }
+        // Helper function to get specific image
+        const getImage = (path) => {
+            if (images.has(path)) {
+                return images.get(path);
+            }
+            // Load on-demand if not already loaded
+            const entry = zipEntries.find(e => e.entryName === path);
+            if (entry) {
+                const buffer = entry.getData();
+                images.set(path, buffer);
+                return buffer;
+            }
+            return undefined;
+        };
+        // Helper function to sample N random images
+        const sample = (count) => {
+            const imagePaths = manifest.images.map(img => img.path);
+            const sampledPaths = [];
+            // Fisher-Yates shuffle for random sampling
+            const shuffled = [...imagePaths];
+            for (let i = shuffled.length - 1; i > 0; i--) {
+                const j = Math.floor(Math.random() * (i + 1));
+                [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+            }
+            // Take first N
+            const selected = shuffled.slice(0, Math.min(count, shuffled.length));
+            // Load and return buffers
+            return selected.map(path => {
+                const buffer = getImage(path);
+                if (!buffer) {
+                    throw new Error(`Failed to load image: ${path}`);
+                }
+                return buffer;
+            });
+        };
+        return {
+            manifest,
+            images: options.loadImages ? images : undefined,
+            sample,
+            getImage,
+        };
+    }
+    /**
+     * Read only the manifest without loading images
+     */
+    static readManifest(filePath) {
+        const result = VREFReader.read(filePath, { loadImages: false });
+        return result.manifest;
+    }
+    /**
+     * Validate a .vref file
+     */
+    static validate(filePath) {
+        const errors = [];
+        try {
+            if (!fs.existsSync(filePath)) {
+                errors.push('File does not exist');
+                return { valid: false, errors };
+            }
+            const zip = new adm_zip_1.default(filePath);
+            const zipEntries = zip.getEntries();
+            // Check for manifest
+            const manifestEntry = zipEntries.find(entry => entry.entryName === 'manifest.json');
+            if (!manifestEntry) {
+                errors.push('manifest.json not found');
+                return { valid: false, errors };
+            }
+            // Parse manifest
+            let manifest;
+            try {
+                const manifestData = manifestEntry.getData().toString('utf8');
+                manifest = JSON.parse(manifestData);
+            }
+            catch (error) {
+                errors.push('Failed to parse manifest.json');
+                return { valid: false, errors };
+            }
+            // Validate format
+            if (manifest.format !== 'VREF') {
+                errors.push('Invalid format identifier (expected "VREF")');
+            }
+            // Validate version
+            if (!manifest.version) {
+                errors.push('Missing version field');
+            }
+            // Validate image count
+            const actualImageCount = zipEntries.filter(e => e.entryName !== 'manifest.json').length;
+            if (manifest.imageCount !== actualImageCount) {
+                errors.push(`Image count mismatch: manifest says ${manifest.imageCount}, found ${actualImageCount}`);
+            }
+            // Validate all images listed in manifest exist
+            for (const imageInfo of manifest.images) {
+                const entry = zipEntries.find(e => e.entryName === imageInfo.path);
+                if (!entry) {
+                    errors.push(`Image listed in manifest not found: ${imageInfo.path}`);
+                }
+            }
+            return {
+                valid: errors.length === 0,
+                errors,
+            };
+        }
+        catch (error) {
+            errors.push(`Unexpected error: ${error}`);
+            return { valid: false, errors };
+        }
+    }
+}
+exports.VREFReader = VREFReader;

package/dist/VREFWriter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * VREFWriter - Creates .vref files
+ * Harpia AI Research
+ */
+import { VREFCreateOptions } from './types';
+export declare class VREFWriter {
+    private images;
+    private options;
+    constructor(options: VREFCreateOptions);
+    /**
+     * Add an image from a file path
+     */
+    addImageFromFile(filePath: string): void;
+    /**
+     * Add an image from a buffer
+     */
+    addImage(fileName: string, buffer: Buffer): void;
+    /**
+     * Add multiple images from a directory
+     */
+    addImagesFromDirectory(dirPath: string, recursive?: boolean): void;
+    /**
+     * Write the .vref file
+     */
+    write(outputPath: string): void;
+    /**
+     * Validate image format
+     */
+    private isValidImageFormat;
+    /**
+     * Validate image buffer by checking magic bytes
+     */
+    private isValidImageBuffer;
+    /**
+     * Get image dimensions (basic implementation for PNG and JPEG)
+     */
+    private getImageDimensions;
+    /**
+     * Get current image count
+     */
+    getImageCount(): number;
+    /**
+     * Clear all images
+     */
+    clear(): void;
+}

package/dist/VREFWriter.js

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * VREFWriter - Creates .vref files
+ * Harpia AI Research
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VREFWriter = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const adm_zip_1 = __importDefault(require("adm-zip"));
+const types_1 = require("./types");
+class VREFWriter {
+    constructor(options) {
+        this.images = new Map();
+        this.options = options;
+    }
+    /**
+     * Add an image from a file path
+     */
+    addImageFromFile(filePath) {
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        const buffer = fs.readFileSync(filePath);
+        const fileName = path.basename(filePath);
+        this.addImage(fileName, buffer);
+    }
+    /**
+     * Add an image from a buffer
+     */
+    addImage(fileName, buffer) {
+        const ext = path.extname(fileName).toLowerCase().slice(1);
+        if (!this.isValidImageFormat(ext)) {
+            throw new Error(`Unsupported format: ${ext}. Only images are allowed: ${types_1.SUPPORTED_IMAGE_FORMATS.join(', ')}`);
+        }
+        // Validate that it's actually an image by checking magic bytes
+        if (!this.isValidImageBuffer(buffer, ext)) {
+            throw new Error(`File ${fileName} does not appear to be a valid ${ext} image`);
+        }
+        this.images.set(fileName, buffer);
+    }
+    /**
+     * Add multiple images from a directory
+     */
+    addImagesFromDirectory(dirPath, recursive = false) {
+        if (!fs.existsSync(dirPath)) {
+            throw new Error(`Directory not found: ${dirPath}`);
+        }
+        const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const fullPath = path.join(dirPath, entry.name);
+            if (entry.isDirectory() && recursive) {
+                this.addImagesFromDirectory(fullPath, recursive);
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase().slice(1);
+                if (this.isValidImageFormat(ext)) {
+                    try {
+                        this.addImageFromFile(fullPath);
+                    }
+                    catch (error) {
+                        console.warn(`Skipping ${entry.name}: ${error}`);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Write the .vref file
+     */
+    write(outputPath) {
+        if (this.images.size === 0) {
+            throw new Error('No images added. Cannot create empty .vref file.');
+        }
+        const zip = new adm_zip_1.default();
+        const imageMetadataList = [];
+        // Add all images to ZIP
+        for (const [fileName, buffer] of this.images) {
+            zip.addFile(fileName, buffer);
+            const ext = path.extname(fileName).toLowerCase().slice(1);
+            const dimensions = this.getImageDimensions(buffer, ext);
+            imageMetadataList.push({
+                path: fileName,
+                format: ext,
+                size: buffer.length,
+                width: dimensions?.width,
+                height: dimensions?.height,
+            });
+        }
+        // Create manifest
+        const manifest = {
+            version: '1.0.0',
+            format: 'VREF',
+            fileName: path.basename(outputPath),
+            imageCount: this.images.size,
+            images: imageMetadataList,
+            createdAt: new Date().toISOString(),
+            metadata: {
+                description: this.options.description,
+                tags: this.options.tags,
+                author: this.options.author,
+                license: this.options.license,
+                ...this.options.metadata,
+            },
+        };
+        // Add manifest as JSON
+        zip.addFile('manifest.json', Buffer.from(JSON.stringify(manifest, null, 2)));
+        // Write ZIP file
+        zip.writeZip(outputPath);
+    }
+    /**
+     * Validate image format
+     */
+    isValidImageFormat(format) {
+        return types_1.SUPPORTED_IMAGE_FORMATS.includes(format);
+    }
+    /**
+     * Validate image buffer by checking magic bytes
+     */
+    isValidImageBuffer(buffer, format) {
+        if (buffer.length < 8)
+            return false;
+        switch (format.toLowerCase()) {
+            case 'png':
+                return 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;
+            case 'gif':
+                return buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46;
+            case 'webp':
+                return 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';
+            default:
+                return false;
+        }
+    }
+    /**
+     * Get image dimensions (basic implementation for PNG and JPEG)
+     */
+    getImageDimensions(buffer, format) {
+        try {
+            if (format === 'png' && buffer.length >= 24) {
+                const width = buffer.readUInt32BE(16);
+                const height = buffer.readUInt32BE(20);
+                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)
+                        break;
+                    const marker = buffer[offset + 1];
+                    offset += 2;
+                    if (marker === 0xc0 || marker === 0xc2) {
+                        const height = buffer.readUInt16BE(offset + 3);
+                        const width = buffer.readUInt16BE(offset + 5);
+                        return { width, height };
+                    }
+                    const segmentLength = buffer.readUInt16BE(offset);
+                    offset += segmentLength;
+                }
+            }
+        }
+        catch (error) {
+            // If dimension extraction fails, just return undefined
+            return undefined;
+        }
+        return undefined;
+    }
+    /**
+     * Get current image count
+     */
+    getImageCount() {
+        return this.images.size;
+    }
+    /**
+     * Clear all images
+     */
+    clear() {
+        this.images.clear();
+    }
+}
+exports.VREFWriter = VREFWriter;

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * VREF CLI - Command line interface for creating .vref files
+ * Harpia AI Research
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const VREFWriter_1 = require("./VREFWriter");
+function showHelp() {
+    console.log(`
+┌─────────────────────────────────────────────────┐
+│  VREF CLI v1.0.0                                │
+│  by Harpia AI Research                          │
+│  https://harpiaresearch.cc                      │
+└─────────────────────────────────────────────────┘
+
+Create .vref files from images
+
+USAGE:
+  npx create-vref <input> [options]
+  
+ARGUMENTS:
+  <input>              Path to image file or directory
+
+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
+
+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 \\
+    -n "RPG Sprites" \\
+    -d "Character sprites for RPG games" \\
+    -t "rpg,sprites,pixelart" \\
+    -a "Your Name" \\
+    -l "CC-BY-4.0"
+  `);
+}
+function parseArgs(args) {
+    const options = {
+        input: null,
+        output: 'output.vref',
+        name: null,
+        description: null,
+        tags: null,
+        author: null,
+        license: null,
+        recursive: false,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        switch (arg) {
+            case '-h':
+            case '--help':
+                showHelp();
+                process.exit(0);
+                break;
+            case '-o':
+            case '--output':
+                options.output = args[++i];
+                break;
+            case '-n':
+            case '--name':
+                options.name = args[++i];
+                break;
+            case '-d':
+            case '--desc':
+            case '--description':
+                options.description = args[++i];
+                break;
+            case '-t':
+            case '--tags':
+                options.tags = args[++i].split(',').map((t) => t.trim());
+                break;
+            case '-a':
+            case '--author':
+                options.author = args[++i];
+                break;
+            case '-l':
+            case '--license':
+                options.license = args[++i];
+                break;
+            case '-r':
+            case '--recursive':
+                options.recursive = true;
+                break;
+            default:
+                if (!arg.startsWith('-')) {
+                    options.input = arg;
+                }
+                break;
+        }
+    }
+    return options;
+}
+function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        showHelp();
+        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');
+        process.exit(1);
+    }
+    if (!fs.existsSync(options.input)) {
+        console.error(`❌ Error: Input not found: ${options.input}`);
+        process.exit(1);
+    }
+    console.log('┌─────────────────────────────────────────────────┐');
+    console.log('│  VREF CLI v1.0.0                                │');
+    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,
+            description: options.description,
+            tags: options.tags,
+            author: options.author,
+            license: options.license,
+        });
+        console.log(`📂 Input: ${options.input}`);
+        const stat = fs.statSync(options.input);
+        if (stat.isDirectory()) {
+            console.log(`🔍 Scanning directory${options.recursive ? ' (recursive)' : ''}...`);
+            writer.addImagesFromDirectory(options.input, options.recursive);
+        }
+        else if (stat.isFile()) {
+            console.log('📄 Adding image...');
+            writer.addImageFromFile(options.input);
+        }
+        else {
+            throw new Error('Input must be a file or directory');
+        }
+        const imageCount = writer.getImageCount();
+        if (imageCount === 0) {
+            console.error('❌ Error: No valid images found');
+            process.exit(1);
+        }
+        console.log(`✅ Found ${imageCount} valid image${imageCount !== 1 ? 's' : ''}`);
+        console.log(`📦 Creating ${options.output}...`);
+        writer.write(options.output);
+        const stats = fs.statSync(options.output);
+        const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+        console.log(`✅ Success! Created ${options.output} (${sizeMB} MB)`);
+        console.log('\n📋 Metadata:');
+        console.log(`   Images: ${imageCount}`);
+        if (options.name)
+            console.log(`   Name: ${options.name}`);
+        if (options.description)
+            console.log(`   Description: ${options.description}`);
+        if (options.tags)
+            console.log(`   Tags: ${options.tags.join(', ')}`);
+        if (options.author)
+            console.log(`   Author: ${options.author}`);
+        if (options.license)
+            console.log(`   License: ${options.license}`);
+        console.log('\n🚀 Share this file with AI platforms that support VREF!');
+        console.log('   Learn more: https://harpiaresearch.cc\n');
+    }
+    catch (error) {
+        console.error(`\n❌ Error: ${error.message}`);
+        process.exit(1);
+    }
+}
+main();

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * VREF (Visual Reference Format)
+ * Standardized container for curated visual references in AI image generation
+ *
+ * Harpia AI Research
+ * https://harpiaresearch.cc
+ */
+export { VREFWriter } from './VREFWriter';
+export { VREFReader } from './VREFReader';
+export { VREFManifest, VREFCreateOptions, VREFReadOptions, VREFReadResult, ImageMetadata, SupportedImageFormat, SUPPORTED_IMAGE_FORMATS, } from './types';

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * VREF (Visual Reference Format)
+ * Standardized container for curated visual references in AI image generation
+ *
+ * Harpia AI Research
+ * https://harpiaresearch.cc
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_IMAGE_FORMATS = exports.VREFReader = exports.VREFWriter = void 0;
+var VREFWriter_1 = require("./VREFWriter");
+Object.defineProperty(exports, "VREFWriter", { enumerable: true, get: function () { return VREFWriter_1.VREFWriter; } });
+var VREFReader_1 = require("./VREFReader");
+Object.defineProperty(exports, "VREFReader", { enumerable: true, get: function () { return VREFReader_1.VREFReader; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "SUPPORTED_IMAGE_FORMATS", { enumerable: true, get: function () { return types_1.SUPPORTED_IMAGE_FORMATS; } });

package/dist/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * VREF (Visual Reference Format) Type Definitions
+ * Harpia AI Research
+ */
+/**
+ * VREF Manifest structure
+ * Automatically generated and included in every .vref file
+ */
+export interface VREFManifest {
+    /** VREF format version (semver) */
+    version: string;
+    /** Format identifier */
+    format: 'VREF';
+    /** ZIP compression version (if applicable) */
+    zipVersion?: string;
+    /** Name of the .vref file */
+    fileName: string;
+    /** Total number of images in the container */
+    imageCount: number;
+    /** Array of image metadata */
+    images: ImageMetadata[];
+    /** ISO 8601 timestamp of creation */
+    createdAt: string;
+    /** Optional metadata */
+    metadata?: {
+        /** Description of the reference pack */
+        description?: string;
+        /** Tags for categorization */
+        tags?: string[];
+        /** Author information */
+        author?: string;
+        /** License information */
+        license?: string;
+        /** Any additional custom fields */
+        [key: string]: any;
+    };
+}
+/**
+ * Metadata for individual images within the VREF
+ */
+export interface ImageMetadata {
+    /** Relative path within the .vref archive */
+    path: string;
+    /** Image format (png, jpg, jpeg, webp, gif, avif) */
+    format: string;
+    /** File size in bytes */
+    size: number;
+    /** Image width in pixels */
+    width?: number;
+    /** Image height in pixels */
+    height?: number;
+}
+/**
+ * Options for creating a VREF file
+ */
+export interface VREFCreateOptions {
+    /** Name for the output .vref file */
+    fileName: string;
+    /** Optional description */
+    description?: string;
+    /** Optional tags */
+    tags?: string[];
+    /** Optional author */
+    author?: string;
+    /** Optional license */
+    license?: string;
+    /** Additional metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for reading a VREF file
+ */
+export interface VREFReadOptions {
+    /** Whether to extract images to memory */
+    loadImages?: boolean;
+    /** Validate image formats */
+    validate?: boolean;
+}
+/**
+ * Result of reading a VREF file
+ */
+export interface VREFReadResult {
+    /** Parsed manifest */
+    manifest: VREFManifest;
+    /** Image buffers (if loadImages: true) */
+    images?: Map<string, Buffer>;
+    /** Get a random sample of N images */
+    sample: (count: number) => Buffer[];
+    /** Get specific image by path */
+    getImage: (path: string) => Buffer | undefined;
+}
+/**
+ * Supported image formats
+ */
+export declare const SUPPORTED_IMAGE_FORMATS: readonly ["png", "jpg", "jpeg", "webp", "gif", "avif"];
+export type SupportedImageFormat = typeof SUPPORTED_IMAGE_FORMATS[number];

package/dist/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * VREF (Visual Reference Format) Type Definitions
+ * Harpia AI Research
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUPPORTED_IMAGE_FORMATS = void 0;
+/**
+ * Supported image formats
+ */
+exports.SUPPORTED_IMAGE_FORMATS = [
+    'png',
+    'jpg',
+    'jpeg',
+    'webp',
+    'gif',
+    'avif'
+];

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@harpiaresearch/vref",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "create-vref": "./dist/cli.js",
+    "vref": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --test",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "vref",
+    "visual-reference",
+    "ai",
+    "image-generation",
+    "midjourney",
+    "stable-diffusion",
+    "harpia"
+  ],
+  "author": "Harpia AI Research",
+  "license": "BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Harpia-AI-Research/vref"
+  },
+  "dependencies": {
+    "adm-zip": "^0.5.10"
+  },
+  "devDependencies": {
+    "@types/adm-zip": "^0.5.5",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}