@harpiaresearch/vref 0.0.0-stage → 1.0.0

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,366 @@
-# Temporary Holding Version
+# VREF — Visual Reference Format
 
-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.
+> **Standardized container 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) 🇧🇷
+
+---
+
+## What is VREF?
+
+VREF (Visual Reference Format) is an open standard for packaging and sharing curated visual references for AI image generation platforms.
+
+Instead of uploading multiple loose images or struggling to describe complex visual concepts in text, users can:
+
+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
+
+### The Problem
+
+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
+
+### The Solution
+
+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
+
+---
+
+## Installation
+
+```bash
+npm install @harpiaresearch/vref
+```
+
+Or use directly with `npx`:
+
+```bash
+npx create-vref
+```
+
+---
+
+## Quick Start
+
+### Creating a .vref file (CLI)
+
+```bash
+# From a directory of images
+npx create-vref ./my-images -o references.vref
+
+# With metadata
+npx create-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
+```
+
+### Using the library (JavaScript/TypeScript)
+
+**Creating a .vref file:**
+
+```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',
+});
+
+// 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`);
+```
+
+**Reading a .vref file:**
+
+```typescript
+import { VREFReader } from '@harpiaresearch/vref';
+
+// Read the entire .vref 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`);
+});
+
+// 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**
+
+Users upload `.vref` files to platforms like:
+- Midjourney
+- Stable Diffusion
+- DALL-E
+- Replicate
+- Custom AI platforms
+
+The platform extracts random images and sends them as visual context along with the user's text prompt.
+
+### 2. **Game Development**
+
+Distribute reference packs:
+- `rpg-sprites.vref` — Character sprites for RPG games
+- `platformer-tiles.vref` — Tile sets for platformers
+- `ui-elements.vref` — UI design references
+
+### 3. **Training ML Models**
+
+Use `.vref` files as datasets:
+
+```typescript
+import { VREFReader } from '@harpiaresearch/vref';
+import { PixelGenModel } from '@harpiaresearch/pixelgen';
+
+const dataset = VREFReader.read('training-data.vref', { loadImages: true });
+const model = new PixelGenModel(3, 3);
+
+// Train with VREF data
+// ...
+```
+
+### 4. **Design & Creative Work**
+
+Share mood boards and references:
+- `architecture-modern.vref`
+- `color-palettes-warm.vref`
+- `typography-references.vref`
+
+---
+
+## File Format Specification
+
+A `.vref` file is a ZIP container with:
+
+```
+my-pack.vref (ZIP)
+├── manifest.json
+├── image1.png
+├── image2.jpg
+├── image3.webp
+└── ...
+```
+
+### `manifest.json` Structure
+
+```json
+{
+  "version": "1.0.0",
+  "format": "VREF",
+  "fileName": "my-pack.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 X references",
+    "tags": ["tag1", "tag2"],
+    "author": "Author Name",
+    "license": "CC-BY-4.0"
+  }
+}
+```
+
+### Supported Image Formats
+
+- ✅ PNG (`.png`)
+- ✅ JPEG (`.jpg`, `.jpeg`)
+- ✅ WebP (`.webp`)
+- ✅ GIF (`.gif`)
+- ✅ AVIF (`.avif`)
+
+Any other file type is **rejected** with an error.
+
+---
+
+## API Reference
+
+### `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;
+  clear(): void;
+}
+```
+
+### `VREFReader`
+
+```typescript
+class VREFReader {
+  static read(filePath: string, options?: VREFReadOptions): VREFReadResult;
+  static readManifest(filePath: string): VREFManifest;
+  static validate(filePath: string): { valid: boolean; errors: string[] };
+}
+```
+
+### Types
+
+See [src/types.ts](src/types.ts) for complete type definitions.
+
+---
+
+## Platform Integration
+
+### For AI Platform Developers
+
+Integrating VREF support:
+
+```typescript
+import { VREFReader } from '@harpiaresearch/vref';
+
+// 1. User uploads .vref file
+const vref = VREFReader.read(uploadedFile, { loadImages: true });
+
+// 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);
+
+// 4. Get user's text prompt
+const userPrompt = getUserPrompt(); // "A warrior character in pixel art style"
+
+// 5. Send to your AI model
+await generateImage({
+  prompt: userPrompt,
+  referenceImages: selectedImages,
+});
+```
+
+That's it! 🎉
+
+---
+
+## Examples
+
+See the [examples/](examples/) directory for:
+- Creating `.vref` files
+- Reading and sampling images
+- Platform integration examples
+- PixelGen integration
+
+---
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+BSD 3-Clause License
+
+Copyright (c) 2024, Harpia AI Research
+
+See [LICENSE](LICENSE) for full text.
+
+---
+
+## Citation
+
+If you use VREF in your research or project:
+
+```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}
+}
+```
+
+---
+
+## Links
+
+- 🌐 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)
+
+---
+
+**Made with 💚💛 by Harpia AI Research — São Paulo, Brazil** 🇧🇷

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.0",
+  "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"
+  }
+}