Majoor Assets Manager - Documentation Index

Welcome to the documentation hub for Majoor Assets Manager for ComfyUI.

Current Version: 2.4.5 Last Updated: April 14, 2026

Quick Start

New users

1. Installation Guide - Install and set up the extension
2. User Guide (HTML) - Visual walkthrough with screenshots
3. Hotkeys & Shortcuts - Essential keyboard shortcuts
4. Basic Search - Find assets quickly

Returning users

• AI Features Guide - AI-assisted search and enrichment features
• MFV Guide - Dedicated Majoor Floating Viewer walkthrough
• Viewer Feature Tutorial - Floating viewer and analysis tools
• Changelog - Recent releases and fixes
• Architecture Map - Backend boundaries and refactor guide

Privacy And Offline Use

• PRIVACY_OFFLINE.md - Dedicated privacy, offline, and token explanation page
• AI_FEATURES.md - Local AI processing, model downloads, offline behavior, and token clarification
• SECURITY_ENV_VARS.md - Remote access security, API token behavior, and safe defaults
• SETTINGS_CONFIGURATION.md - UI security settings and token storage behavior

Documentation Categories

Getting Started

Core Features

Plugin System

Configuration And Security

Maintenance And Development

Frontend Architecture

Historical Documents

Quality And Verification

Use the canonical gate from the repo root:

python scripts/run_quality_gate.py

Useful variants:

python scripts/run_quality_gate.py --python-only --skip-tests
tox -e quality
npm run test:js

The quality gate enforces:

• UTF-8 text files without BOM
• ruff linting on changed Python files during the migration window
• mypy
• bandit
• pip-audit
• xenon/radon complexity checks
• backend tests
• frontend tests
• npm audit

Security Note

The backend keeps a compatibility-first local security model:

• loopback writes remain allowed by default
• remote writes are denied unless explicitly authorized
• MAJOOR_REQUIRE_AUTH=1 switches to strict token-auth for local writes too

Current releases also support a Settings-first remote setup flow:

• Recommended Remote LAN Setup is the preferred one-click LAN path
• the current browser session exposes its state through the runtime Write auth: indicator inside Assets Manager

That nuance is intentional and is the documented target behavior for current releases.

Majoor Assets Manager — AI Features Guide

Comprehensive guide to AI-powered features in Majoor Assets Manager

Version: 2.4.5 Last Updated: April 15, 2026

---

Table of Contents

• Overview
• AI Models & Technologies
• Enabling AI Features
• Core AI Features
• Semantic Search
• Find Similar
• AI Auto-Tags
• Enhanced Captions (Florence-2)
• Prompt Alignment Score
• Smart Collections
• Discover Groups
• How It Works
• Configuration & Tuning
• Performance Considerations
• Troubleshooting
• API Reference
• Privacy & Security

---

Overview

Majoor Assets Manager includes a suite of AI-powered features that leverage multimodal embedding models to provide semantic search, visual similarity matching, and automated metadata generation. These features help you discover and organize your generated assets more intelligently.

What AI Features Provide

Key Benefits

• Natural Language Search: No need to remember exact filenames or tags
• Visual Discovery: Find assets by appearance, not just metadata
• Automated Organization: Reduce manual tagging workload
• Quality Insights: Understand prompt-image alignment
• Themed Grouping: Automatically discover patterns in your library

---

AI Models & Technologies

Primary Models

Technology Stack

• Sentence Transformers: Model loading and inference
• Faiss: Vector similarity search (Facebook AI Similarity Search)
• Transformers: HuggingFace transformers for model inference
• SQLite with vector extension: Embedding storage

Model Download & Caching

Models are downloaded automatically on first use and cached locally:

Cache Location: ~/.cache/huggingface/hub/
Models:
  - google/siglip-so400m-patch14-384 (SigLIP2)
  - microsoft/xclip-base-patch32 (X-CLIP)
  - microsoft/Florence-2-base (Florence-2)

Initial Download Sizes:

• SigLIP2: ~1.2 GB
• X-CLIP: ~600 MB
• Florence-2: ~800 MB

---

Enabling AI Features

Method 1: Via Settings UI (Recommended)

1. Open Assets Manager panel in ComfyUI
2. Click Settings (gear icon)
3. Find AI Features section
4. Toggle Enable AI semantic search to ON
5. Wait for initial model download (progress shown in console)
6. Click Save Settings

Method 2: Via Environment Variable

Add to your environment before starting ComfyUI:

# Windows (PowerShell)
$env:MJR_AM_ENABLE_VECTOR_SEARCH="1"

# Windows (Command Prompt)
set MJR_AM_ENABLE_VECTOR_SEARCH=1

# Linux/macOS
export MJR_AM_ENABLE_VECTOR_SEARCH=1

Verification

After enabling:

1. Check console for model loading messages:

   INFO: Loading multimodal embedding model 'google/siglip-so400m-patch14-384' …
   INFO: SigLIP2 model loaded and ready: 'google/siglip-so400m-patch14-384' (dim=1152)

1. In Assets Manager, look for:
• Sparkles icon (🔮) in search bar for semantic search toggle
• "Find Similar" button in asset context menu
• AI-related options in Collections panel

Initial Setup Workflow

1. Enable AI features in Settings
   ↓
2. Trigger initial index scan (Ctrl+S)
   ↓
3. Wait for metadata extraction to complete
   ↓
4. Click "Backfill vectors" in Index Status
   ↓
5. Wait for vector embeddings to be computed
   ↓
6. AI features are now fully functional

Per-Asset Vector Operations

You can trigger scan and backfill vectors for individual assets directly from the grid view:

Via Card Status Dot

1. Locate the status indicator on an asset card (small dot in corner)
2. Click the status dot to open the asset actions menu
3. Select one of:
• "Index Asset" — Trigger metadata scan for this asset only
• "Generate Vector" — Compute AI embedding for this asset
• "Re-index" — Force re-scan and re-compute vectors

Via Sparkles Icon (Prime Icon)

1. Hover over an asset card to reveal action buttons
2. Click the sparkles icon (🔮) if visible on the card
3. Choose from AI-specific actions:
• Generate Caption — Run Florence-2 captioning
• Compute Alignment — Calculate prompt alignment score
• Suggest Tags — Generate AI auto-tags
• Find Similar — Show visually similar assets

When to Use Per-Asset Operations

Visual Indicators

<div class="tip"> <strong>💡 Tip:</strong> For best results, run a full backfill first, then use per-asset operations to update individual items as needed. </div>

---

Core AI Features

1. Semantic Search

Search your asset library using natural language queries instead of keywords.

How to Use

1. Open Assets Manager panel
2. Click the sparkles icon (🔮) in the search bar to enable semantic mode
3. Type a natural language query:
• "sunset over mountains with orange sky"
• "cyberpunk city at night"
• "portrait of a woman with blue hair"
4. Press Enter to search

Query Examples

How It Works

1. Your query is converted to a text embedding using SigLIP2
2. The embedding is compared against all indexed image embeddings
3. Results are ranked by cosine similarity (closest matches first)
4. Results are hydrated with full asset metadata for display

Tips

• Be descriptive: "sunset beach with palm trees" works better than "beach"
• Use color words: "green forest", "blue ocean", "red sunset"
• Include style keywords: "anime", "photorealistic", "cyberpunk"
• Semantic search works across languages (FR → EN auto-translation)

---

2. Find Similar

Discover assets visually similar to a selected asset.

How to Use

1. Select an asset in the grid view (click once)
2. Right-click → Find Similar (or click the Clone icon)
3. View visually similar assets ranked by similarity score
4. Adjust top_k parameter to show more/fewer results (default: 20)

Use Cases

• Variation Discovery: Find successful variations of a generation
• Style Exploration: Discover assets with similar aesthetic
• Quality Comparison: Compare different attempts at same prompt
• Theme Grouping: Find all assets matching a visual theme

Similarity Score

Results include a similarity score (0.0 to 1.0):

• 0.85+: Very similar (near-duplicates or variations)
• 0.70-0.85: Highly similar (same theme/style)
• 0.55-0.70: Moderately similar (related concepts)
• <0.55: Loosely related (shared elements only)

Technical Details

• Reference asset is excluded from results
• Uses cosine similarity in embedding space
• Searches across all scopes (Outputs, Inputs, Custom)
• Respects current scope filter if applied

---

3. AI Auto-Tags

Automatically suggested tags based on image content analysis.

How It Works

1. Image embedding is compared against predefined tag vocabulary
2. Tags with similarity above threshold are suggested
3. Auto-tags are stored separately from user tags
4. Tags can be viewed and applied to assets

Available Auto-Tags

The system includes 20+ canonical tags:

How to View Auto-Tags

1. Open an asset in the Viewer
2. Look at the Sidebar → AI Tags section
3. See suggested tags with confidence scores

How to Apply Auto-Tags

1. In Viewer sidebar, click Apply All to add all AI tags
2. Or click individual tags to add selectively
3. Tags are merged with your existing tags

Configuration

Adjust sensitivity via environment variable:

# Lower threshold = more tags (less precise)
# Higher threshold = fewer tags (more precise)
MJR_AM_VECTOR_AUTOTAG_THRESHOLD=0.06  # Default

---

4. Enhanced Captions (Florence-2)

Generate detailed AI-powered image descriptions.

How to Generate

1. Open an asset in the Viewer
2. In the sidebar, find Image Description section
3. Click Generate button
4. Wait for caption generation (5-30 seconds)
5. Generated caption appears in sidebar

Caption Quality

Florence-2 generates detailed, descriptive captions:

Example Input: Anime-style image of a girl with blue hair

Generated Caption:

"An anime-style illustration of a young woman with long flowing blue hair and large expressive eyes. She is wearing a school uniform with a white shirt and blue skirt. The background shows a soft gradient of pink and purple, suggesting a sunset or dawn setting. The art style is typical of modern anime with clean lines and vibrant colors."

Use Cases

• Accessibility: Describe images for visually impaired users
• Search Enhancement: Captions are indexed for semantic search
• Documentation: Auto-generate descriptions for asset catalogs
• Prompt Analysis: Compare generated caption with original prompt

Batch Generation

For multiple assets, use the API:

POST /mjr/am/vector/caption/{asset_id}

Or use the "Backfill vectors" feature which generates captions for all images.

Storage

• Captions stored in asset_metadata.enhanced_caption field
• Persisted in SQLite database
• Survives index resets (stored separately from vectors)

---

5. Prompt Alignment Score

Measure how well an image matches its generation prompt.

What It Measures

The alignment score quantifies the semantic similarity between:

• The original generation prompt (from metadata)
• The visual content of the image (from embedding)

Score Interpretation

How It's Calculated

The score uses multi-signal fusion:

1. Multi-segment image↔text score (60% weight)
• Prompt split into segments
• Each segment scored against image
• Length-weighted average with best-segment bonus

1. Caption↔prompt text similarity (20% weight)
• Florence-2 caption compared to prompt
• Text-to-text coherence measure

1. Semantic dimension score (20% weight)
• Subject, style, medium, mood, color dimensions
• Each dimension scored separately

Negative Prompt Penalty: If negative prompt exists, its similarity to image reduces the score (penalizes unwanted content leakage).

How to View

1. Open asset in Viewer
2. Look for Prompt Alignment section in sidebar
3. Score displayed as percentage (0-100%)

Use Cases

• Quality Control: Identify generations that didn't match intent
• Prompt Engineering: Refine prompts based on alignment feedback
• Curation: Filter library by alignment quality
• Model Comparison: Compare different models' prompt adherence

---

6. Smart Collections

Automatically create collections based on AI suggestions.

How to Use

1. Open Collections panel
2. Click Smart Suggestions button
3. Review AI-suggested collections
4. Click Create to accept a suggestion

Suggestion Types

The AI analyzes your library and suggests:

• Theme-based: "Cyberpunk Collection", "Nature Scenes"
• Style-based: "Anime Collection", "Photorealistic"
• Color-based: "Blue Tones", "Warm Colors"
• Subject-based: "Portraits", "Landscapes", "Vehicles"

How Suggestions Work

1. Asset embeddings are clustered using k-means
2. Each cluster is analyzed for common themes
3. Representative tags and descriptions generated
4. Suggestions presented for approval

Configuration

Adjust number of suggestions:

{
  "k": 8  // Number of clusters (2-20)
}

More clusters = more specific collections Fewer clusters = broader collections

---

7. Discover Groups

Cluster your entire library by visual similarity.

How to Use

1. Open Collections panel
2. Click Discover Groups button
3. Wait for clustering to complete
4. Browse discovered groups
5. Convert groups to collections as desired

Group Characteristics

Each group includes:

• Preview: Sample images from the group
• Size: Number of assets in group
• Tags: Common AI-suggested tags
• Representative Query: Natural language description

Use Cases

• Library Exploration: Discover patterns in your assets
• Cleanup: Identify duplicate or near-duplicate generations
• Curation: Find themed subsets for projects
• Analysis: Understand your generation habits

Performance

Clustering time depends on library size:

---

How It Works

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Assets Manager UI                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │ Semantic │  │   Find   │  │   Auto   │  │  Smart   │   │
│  │  Search  │  │ Similar  │  │  Tags    │  │Collections│  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘   │
└───────┼─────────────┼─────────────┼─────────────┼──────────┘
        │             │             │             │
        └─────────────┴─────────────┴─────────────┘
                          │
                    HTTP API
                          │
┌─────────────────────────┼─────────────────────────────────┐
│              Majoor Backend (Python)                      │
│  ┌──────────────────────┴──────────────────────────┐     │
│  │           Vector Service Layer                  │     │
│  │  ┌────────────┐  ┌────────────┐  ┌──────────┐  │     │
│  │  │  SigLIP2   │  │   X-CLIP   │  │Florence-2│  │     │
│  │  │  (Image)   │  │  (Video)   │  │ (Caption)│  │     │
│  │  └─────┬──────┘  └─────┬──────┘  └────┬─────┘  │     │
│  └────────┼───────────────┼──────────────┼────────┘     │
│           │               │              │              │
│  ┌────────┴───────────────┴──────────────┴──────────┐   │
│  │              Faiss Index (In-Memory)             │   │
│  └──────────────────────┬───────────────────────────┘   │
│                         │                                │
│  ┌──────────────────────┴───────────────────────────┐   │
│  │        SQLite (asset_embeddings table)           │   │
│  │  - asset_id                                      │   │
│  │  - vector (BLOB)                                 │   │
│  │  - aesthetic_score                               │   │
│  │  - auto_tags (JSON)                              │   │
│  │  - enhanced_caption                              │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Embedding Pipeline

1. Asset Discovery
   ↓
2. Metadata Extraction (ExifTool, FFprobe)
   ↓
3. Vector Embedding Computation
   ├─ Image → SigLIP2 image encoder
   ├─ Video → X-CLIP video encoder (keyframes)
   └─ Text → SigLIP2 text encoder
   ↓
4. Embedding Storage
   └─ SQLite: asset_embeddings table
   ↓
5. Index Building
   └─ Faiss IndexFlatIP (cosine similarity)
   ↓
6. Query Processing
   ├─ Text query → text embedding
   ├─ Image query → image embedding
   └─ Similarity search → ranked results

Vector Storage Schema

CREATE TABLE asset_embeddings (
    asset_id INTEGER PRIMARY KEY,
    vector BLOB NOT NULL,           -- Packed float32 array
    model_name TEXT NOT NULL,       -- e.g., "google/siglip-so400m-patch14-384"
    aesthetic_score REAL,           -- Prompt alignment score (0-1)
    auto_tags TEXT,                 -- JSON array of tag strings
    enhanced_caption TEXT,          -- Florence-2 generated caption
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

---

Configuration & Tuning

Environment Variables

Model Selection

Image/Text Model Options

Video Model Options

Caption Model Options

Tuning Examples

Faster Embedding (Lower Quality)

export MJR_AM_VECTOR_MODEL="google/siglip-base-patch16-224"
export MJR_AM_VECTOR_BATCH_SIZE=64
export MJR_AM_VECTOR_DIM=768

Higher Quality (Slower)

export MJR_AM_VECTOR_MODEL="google/siglip-large-patch16-384"
export MJR_AM_PROMPT_MODEL="microsoft/Florence-2-large"
export MJR_AM_VECTOR_AUTOTAG_THRESHOLD=0.30

Low-RAM System

export MJR_AM_VECTOR_BATCH_SIZE=8
export MJR_AM_VECTOR_MODEL="google/siglip-base-patch16-224"

---

Performance Considerations

Resource Requirements

Model Loading Times

Embedding Speed

Backfill Performance

Backfill vectors computes embeddings for all assets without vectors:

Optimization Tips

1. Enable GPU acceleration (CUDA):

   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

1. Adjust batch size for your hardware:
• Low RAM: MJR_AM_VECTOR_BATCH_SIZE=8
• High RAM: MJR_AM_VECTOR_BATCH_SIZE=64

1. Use CPU-only mode if GPU memory is limited:

   export CUDA_VISIBLE_DEVICES=""

1. Limit index size for large libraries:
• Vector searcher caps at 100,000 assets
• Most recent assets prioritized

1. Schedule backfill during off-hours:
• Run overnight for large libraries
• System remains usable during backfill

---

Troubleshooting

Common Issues

1. AI Features Not Appearing

Symptoms: No sparkles icon, no "Find Similar" button

Solutions:

• Check if AI features are enabled in Settings
• Verify MJR_AM_ENABLE_VECTOR_SEARCH=1 in environment
• Restart ComfyUI after enabling
• Check console for model loading errors

2. Model Download Fails

Symptoms: Error downloading models, timeout

Solutions:

# Check internet connectivity
ping huggingface.co

# Manual model download
huggingface-cli download google/siglip-so400m-patch14-384

# Set HF mirror (for China/regions with restrictions)
export HF_ENDPOINT=https://hf-mirror.com

3. Out of Memory (OOM)

Symptoms: System freezes, crashes during embedding

Solutions:

• Reduce batch size: MJR_AM_VECTOR_BATCH_SIZE=8
• Close other applications
• Use CPU-only mode to free GPU RAM
• Restart ComfyUI to clear memory

4. Slow Performance

Symptoms: Searches take >5 seconds, UI lag

Solutions:

• Reduce library size (split into multiple scopes)
• Use GPU acceleration if available
• Increase system RAM
• Disable verbose logging: MJR_AM_AI_VERBOSE_LOGS=0

5. Poor Search Results

Symptoms: Irrelevant results for queries

Solutions:

• Ensure vectors are backfilled: Index Status → Backfill vectors
• Use more descriptive queries
• Check model loaded correctly in console
• Verify embedding dimension matches model

6. Caption Generation Fails

Symptoms: "Generate" button shows error, no caption

Solutions:

• Check Florence-2 model loaded (console logs)
• Verify asset is an image (not video)
• Increase timeout: MJR_AM_DB_TIMEOUT=120
• Check disk space for model cache

Diagnostic Commands

# Check model cache
ls -la ~/.cache/huggingface/hub/

# Verify Python packages
pip list | grep -E "sentence-transformers|transformers|faiss"

# Test model loading
python -c "from sentence_transformers import SentenceTransformer; m = SentenceTransformer('google/siglip-so400m-patch14-384'); print('OK')"

# Check vector index status
curl http://localhost:8188/mjr/am/vector/stats

Log Analysis

Enable verbose logging for debugging:

export MJR_AM_AI_VERBOSE_LOGS=1

Look for these log patterns:

# Successful model load
INFO: Loading multimodal embedding model 'google/siglip-so400m-patch14-384' …
INFO: SigLIP2 model loaded and ready: 'google/siglip-so400m-patch14-384' (dim=1152)

# Successful embedding
DEBUG: Vector embedding computed for asset 12345

# Search query
INFO: Semantic search: 'sunset mountains' → 20 results

---

API Reference

Semantic Search

GET /mjr/am/vector/search?q={query}&top_k={count}&scope={scope}

Parameters:

• q (required): Natural language query
• top_k (optional): Max results (default: 20, max: 200)
• scope (optional): output, input, custom, all

Example:

curl "http://localhost:8188/mjr/am/vector/search?q=sunset%20beach&top_k=10"

Response:

{
  "ok": true,
  "data": [
    {
      "id": 12345,
      "asset_id": 12345,
      "filepath": "/path/to/image.png",
      "filename": "image.png",
      "kind": "image",
      "_vectorScore": 0.8923
    }
  ]
}

Find Similar

GET /mjr/am/vector/similar/{asset_id}?top_k={count}

Parameters:

• asset_id (required): Reference asset ID
• top_k (optional): Max results (default: 20)

Example:

curl "http://localhost:8188/mjr/am/vector/similar/12345?top_k=10"

Prompt Alignment

GET /mjr/am/vector/alignment/{asset_id}

Response:

{
  "ok": true,
  "data": 0.7523
}

Generate Caption

POST /mjr/am/vector/caption/{asset_id}

Response:

{
  "ok": true,
  "data": "An anime-style illustration of..."
}

Auto-Tags

GET /mjr/am/vector/auto-tags/{asset_id}

Response:

{
  "ok": true,
  "data": ["anime", "portrait", "fantasy"]
}

Suggest Collections

POST /mjr/am/vector/suggest-collections
Content-Type: application/json

{"k": 8}

Response:

{
  "ok": true,
  "data": {
    "suggestions": [
      {
        "name": "Cyberpunk Collection",
        "query": "cyberpunk neon city night",
        "estimated_size": 45,
        "tags": ["cyberpunk", "sci-fi", "night"]
      }
    ]
  }
}

Vector Stats

GET /mjr/am/vector/stats

Response:

{
  "ok": true,
  "data": {
    "total": 1234,
    "avg_score": 0.6523,
    "dim": 1152,
    "enabled": true
  }
}

Re-index Asset

POST /mjr/am/vector/index/{asset_id}

Force re-computation of embedding for a single asset.

---

Privacy & Security

For a dedicated user-facing explanation focused on privacy, offline behavior, and token meaning, see PRIVACY_OFFLINE.md.

Data Privacy

• Local Processing: All AI inference runs locally on your machine
• No Cloud Upload: Images and prompts never leave your computer
• Local Cache: Models cached in ~/.cache/huggingface/hub/
• No Telemetry: No usage data sent to developers

In practice, semantic search, find-similar, prompt alignment, caption generation, and auto-tagging run against models loaded inside your local ComfyUI / Majoor process after those models are available locally.

Network Access

Initial model download requires internet access:

• Downloads from HuggingFace CDN
• One-time download per model
• Subsequent uses work offline
• Optional HuggingFace token only affects HuggingFace Hub downloads and rate limits

Token Clarification

Majoor exposes two different token concepts that are easy to confuse:

• HuggingFace token: optional, used for downloading model files from HuggingFace Hub with better rate limits. It is not a hosted AI inference key.
• Majoor API token: used to secure remote write access to the local Majoor backend when ComfyUI is reachable over LAN, reverse proxy, or tunnel. It is not used to send prompts or images to an external AI service.

Offline Use

Offline use is supported once the required models are already cached locally.

• If AI models are already present in the HuggingFace cache, AI features can run without internet access.
• If models are not cached yet, the first model bootstrap requires network access.
• Non-AI Majoor features do not depend on HuggingFace model downloads.

Security Considerations

1. Model Integrity: Models downloaded from official HuggingFace repos
2. Model Code Surface: AI inference is local, but some model loading still depends on upstream HuggingFace/Transformers model packages and compatibility loaders
3. Sandboxing: Models run in same process as ComfyUI
4. Resource Limits: Built-in rate limiting prevents abuse

Environment Isolation

For enhanced security, run in isolated environment:

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

# Install dependencies
pip install -r requirements.txt -r requirements-vector.txt

---

Appendix: Model Cards

SigLIP2 SO400M

• Publisher: Google
• Architecture: Vision-Language Transformer
• Training: Contrastive image-text pairs
• License: Apache 2.0
• HuggingFace: https://huggingface.co/google/siglip-so400m-patch14-384

X-CLIP Base

• Publisher: Microsoft
• Architecture: Video-Language Transformer
• Training: Video-text pairs
• License: MIT
• HuggingFace: https://huggingface.co/microsoft/xclip-base-patch32

Florence-2 Base

• Publisher: Microsoft
• Architecture: Vision-Language Model
• Training: Image-caption pairs
• License: MIT
• HuggingFace: https://huggingface.co/microsoft/Florence-2-base

---

Changelog

v2.4.0 (March 2026)

• Added Florence-2 caption generation
• Improved prompt alignment scoring with multi-signal fusion
• Added French-to-English query translation
• Enhanced auto-tag vocabulary (20+ tags)
• Smart Collections with k-means clustering

v2.3.0 (February 2026)

• Initial AI features release
• Semantic search with SigLIP2
• Find Similar functionality
• Basic auto-tagging

---

Support & Resources

Documentation

• Main Documentation Index
• API Reference
• Configuration Guide

Community

• GitHub Issues
• GitHub Discussions

Model Documentation

• Sentence Transformers Docs
• HuggingFace Transformers
• Faiss Documentation

---

This documentation is part of the Majoor Assets Manager project. Copyright © 2026 Ewald ALOEBOETOE (MajoorWaldi)

Majoor API Reference

Base Path: /mjr/am Version: 2.4.5 Last Updated: April 7, 2026

---

Compatibility

Versioning

• Current API: /mjr/am/* (unversioned, stable)
• Version Alias: /mjr/am/v1/ → redirects to /mjr/am/ (308 Permanent Redirect)
• Legacy Alias: /majoor/version → redirects to /mjr/am/version

Authentication

Most endpoints require authentication when ComfyUI auth is enabled:

• Read operations: May work without auth (depends on configuration)
• Write operations: Require authentication or API token
• CSRF Protection: All state-changing endpoints require X-Requested-With: XMLHttpRequest or X-CSRF-Token

API Token

For remote access or when MAJOOR_API_TOKEN is configured:

X-MJR-Token: <your-token>
# OR
Authorization: Bearer <your-token>

---

Table of Contents

• Health &amp; Diagnostics
• Settings &amp; Configuration
• Search &amp; Discovery
• Asset Operations
• Indexing &amp; Scanning
• Collections &amp; Custom Roots
• Viewer &amp; Metadata
• Download &amp; Export
• Database Maintenance
• Utilities

---

Health & Diagnostics

Health Summary

GET /mjr/am/health

Response: Extension health summary including version, status, and basic metrics.

{
  "ok": true,
  "data": {
    "version": "2.4.5",
    "status": "healthy",
    "indexed_count": 1234,
    "scopes_available": ["output", "input", "custom", "collections"]
  }
}

---

Health Counters

GET /mjr/am/health/counters

Response: Indexed counters for all scopes.

{
  "ok": true,
  "data": {
    "output": { "count": 1000, "last_scan": "2026-02-28T10:00:00Z" },
    "input": { "count": 200, "last_scan": "2026-02-28T10:00:00Z" },
    "custom": { "count": 34, "last_scan": "2026-02-28T10:00:00Z" },
    "collections": { "count": 5 }
  }
}

---

Database Health

GET /mjr/am/health/db

Response: Database diagnostics including schema version, integrity status, and statistics.

{
  "ok": true,
  "data": {
    "schema_version": 7,
    "integrity_check": "ok",
    "page_count": 1024,
    "freelist_count": 128,
    "cache_size": 2000
  }
}

---

Runtime Configuration

GET /mjr/am/config

Response: Current runtime configuration snapshot.

{
  "ok": true,
  "data": {
    "output_directory": "/path/to/output",
    "index_directory": "/path/to/_mjr_index",
    "media_probe_backend": "auto",
    "db_timeout": 30.0,
    "max_connections": 8,
    "safe_mode": true,
    "allow_symlinks": false
  }
}

---

Version Information

GET /mjr/am/version

Response: Extension version and build information.

{
  "ok": true,
  "data": {
    "version": "2.4.5",
    "branch": "main",
    "build_date": "2026-03-29",
    "python_version": "3.11.0",
    "comfyui_version": "0.13.0"
  }
}

---

Tool Status

GET /mjr/am/tools/status

Response: Availability status of external tools (ExifTool, FFprobe).

{
  "ok": true,
  "data": {
    "exiftool": { "available": true, "version": "12.40" },
    "ffprobe": { "available": true, "version": "6.0" },
    "backend": "both"
  }
}

---

Settings & Configuration

Probe Backend Settings

GET  /mjr/am/settings/probe-backend
POST /mjr/am/settings/probe-backend

GET: Read current probe mode. POST: Set probe mode.

Request Body (POST):

{
  "mode": "auto"  // "auto", "exiftool", "ffprobe", "both"
}

Response:

{
  "ok": true,
  "data": {
    "mode": "auto",
    "available": ["exiftool", "ffprobe"]
  }
}

---

Output Directory Override

GET  /mjr/am/settings/output-directory
POST /mjr/am/settings/output-directory

GET: Read output directory override. POST: Set output directory override.

Request Body (POST):

{
  "path": "/path/to/custom/output"
}

Response:

{
  "ok": true,
  "data": {
    "path": "/path/to/custom/output",
    "exists": true,
    "writable": true
  }
}

Index Directory Override

GET  /mjr/am/settings/index-directory
POST /mjr/am/settings/index-directory

GET: Read the current index directory path.

Response:

{
  "ok": true,
  "data": {
    "index_directory": "/path/to/_mjr_index"
  }
}

POST: Set a new index directory path.

Requires write access (loopback or valid X-MJR-Token).

Request Body (POST):

{
  "index_directory": "/path/to/local/mjr_index"
}

Send an empty string to clear the override and revert to the default (<output>/_mjr_index/):

{
  "index_directory": ""
}

Response (POST):

{
  "ok": true,
  "data": {
    "index_directory": "/path/to/local/mjr_index",
    "requires_restart": true
  }
}

The new path is persisted to the .mjr_index_directory_override sidecar file and the in-process environment variables. The change takes effect after ComfyUI is restarted.

Error codes:

---

Metadata Fallback Toggles

GET  /mjr/am/settings/metadata-fallback
POST /mjr/am/settings/metadata-fallback

GET: Read fallback toggles for metadata extraction. POST: Set fallback toggles.

Request Body (POST):

{
  "image": true,   // Use internal parser if ExifTool fails
  "media": true    // Use hachoir if ffprobe unavailable
}

Response:

{
  "ok": true,
  "data": {
    "image": true,
    "media": true
  }
}

---

Search & Discovery

Search with Filters

GET /mjr/am/search

Query Parameters:

Example:

GET /mjr/am/search?q=fantasy&scope=output&kind=image&min_rating=4&sort=date&order=desc&page=1&page_size=50

Response:

{
  "ok": true,
  "data": {
    "total": 150,
    "page": 1,
    "page_size": 50,
    "total_pages": 3,
    "items": [
      {
        "id": "asset_123",
        "filename": "fantasy_character.png",
        "path": "/path/to/output/fantasy_character.png",
        "type": "image",
        "size": 2048576,
        "width": 1024,
        "height": 1536,
        "rating": 5,
        "tags": ["fantasy", "character"],
        "created_at": "2026-02-28T10:00:00Z",
        "metadata": {
          "prompt": "A fantasy character...",
          "model": "SDXL",
          "steps": 30
        }
      }
    ]
  }
}

---

List Assets (Paginated)

GET /mjr/am/list

Query Parameters: Same as search, but without q parameter.

Purpose: List assets without full-text search (faster for browsing).

---

Asset Details

GET /mjr/am/asset/{asset_id}

Response: Full asset details including metadata.

{
  "ok": true,
  "data": {
    "id": "asset_123",
    "filename": "fantasy_character.png",
    "path": "/path/to/output/fantasy_character.png",
    "type": "image",
    "extension": "png",
    "size": 2048576,
    "width": 1024,
    "height": 1536,
    "rating": 5,
    "tags": ["fantasy", "character"],
    "created_at": "2026-02-28T10:00:00Z",
    "modified_at": "2026-02-28T10:00:00Z",
    "metadata": {
      "prompt": "A fantasy character...",
      "negative_prompt": "ugly, blurry",
      "model": "SDXL",
      "sampler": "DPM++ 2M Karras",
      "steps": 30,
      "cfg_scale": 7.0,
      "seed": 123456789,
      "workflow": { ... }
    },
    "thumbnails": {
      "small": "/mjr/am/thumbnail/asset_123?size=small",
      "medium": "/mjr/am/thumbnail/asset_123?size=medium",
      "large": "/mjr/am/thumbnail/asset_123?size=large"
    }
  }
}

---

Metadata Lookup

GET /mjr/am/metadata

Query Parameters:

Example:

GET /mjr/am/metadata?type=output&filename=image.png&subfolder=2026-02-28

Response:

{
  "ok": true,
  "data": {
    "filename": "image.png",
    "path": "/path/to/output/2026-02-28/image.png",
    "metadata": { ... }
  }
}

---

Asset Operations

Update Rating

POST /mjr/am/asset/rating

Request Body:

{
  "asset_id": "asset_123",
  "rating": 5  // 0-5
}

Response:

{
  "ok": true,
  "data": {
    "asset_id": "asset_123",
    "rating": 5,
    "synced_to_file": true
  }
}

---

Update Tags

POST /mjr/am/asset/tags

Request Body:

{
  "asset_id": "asset_123",
  "tags": ["fantasy", "character", "sdxl"]
}

Response:

{
  "ok": true,
  "data": {
    "asset_id": "asset_123",
    "tags": ["fantasy", "character", "sdxl"],
    "synced_to_file": true
  }
}

---

Rename Asset

POST /mjr/am/asset/rename

Request Body:

{
  "asset_id": "asset_123",
  "new_filename": "new_name.png"
}

Response:

{
  "ok": true,
  "data": {
    "asset_id": "asset_123",
    "old_path": "/path/to/old_name.png",
    "new_path": "/path/to/new_name.png"
  }
}

Note: Requires MAJOOR_ALLOW_RENAME=1 if Safe Mode is enabled.

---

Delete Single Asset

POST /mjr/am/asset/delete

Request Body:

{
  "asset_id": "asset_123"
}

Response:

{
  "ok": true,
  "data": {
    "asset_id": "asset_123",
    "deleted": true,
    "path": "/path/to/deleted_file.png"
  }
}

Note: Requires MAJOOR_ALLOW_DELETE=1 if Safe Mode is enabled.

---

Bulk Delete Assets

POST /mjr/am/assets/delete

Request Body:

{
  "asset_ids": ["asset_123", "asset_124", "asset_125"]
}

Response:

{
  "ok": true,
  "data": {
    "deleted_count": 3,
    "deleted_ids": ["asset_123", "asset_124", "asset_125"],
    "failed": []
  }
}

Note: Requires MAJOOR_ALLOW_DELETE=1 if Safe Mode is enabled.

---

Open in Folder

POST /mjr/am/open-in-folder

Request Body:

{
  "asset_id": "asset_123"
}

Response:

{
  "ok": true,
  "data": {
    "asset_id": "asset_123",
    "path": "/path/to/output",
    "opened": true
  }
}

Note: Requires MAJOOR_ALLOW_OPEN_IN_FOLDER=1 if Safe Mode is enabled.

---

Stage to Input

POST /mjr/am/stage-to-input

Request Body:

{
  "asset_id": "asset_123"
}

Response:

{
  "ok": true,
  "data": {
    "asset_id": "asset_123",
    "staged_path": "/path/to/input/staged_file.png",
    "staged": true
  }
}

Purpose: Copy/link asset to ComfyUI input directory for workflow use.

---

Indexing & Scanning

Scan Scope/Root

POST /mjr/am/scan

Request Body:

{
  "scope": "output",      // "output", "input", "custom"
  "root_id": null,        // Custom root ID (for custom scope)
  "incremental": true,    // Incremental scan (default)
  "force": false          // Force full rescan
}

Response:

{
  "ok": true,
  "data": {
    "scan_id": "scan_123",
    "scope": "output",
    "status": "started",
    "estimated_duration_ms": 5000
  }
}

Note: Scan runs in background. Status available via health endpoints.

---

Index Explicit Files

POST /mjr/am/index-files

Request Body:

{
  "files": [
    {
      "filename": "image.png",
      "subfolder": "2026-02-28",
      "type": "output"
    }
  ],
  "origin": "generation"  // "generation", "manual", "import"
}

Response:

{
  "ok": true,
  "data": {
    "indexed_count": 1,
    "failed": []
  }
}

Purpose: Index specific files (used for real-time generation tracking).

---

Reset Index

POST /mjr/am/index/reset

Request Body:

{
  "scope": "output",      // Scope to reset
  "clear_assets": true,   // Clear asset records
  "clear_metadata": true, // Clear metadata cache
  "clear_fts": true,      // Clear full-text search index
  "clear_journal": true   // Clear scan journal
}

Response:

{
  "ok": true,
  "data": {
    "scope": "output",
    "reset": true,
    "rescan_triggered": true
  }
}

---

Collections & Custom Roots

List Collections

GET /mjr/am/collections

Response:

{
  "ok": true,
  "data": {
    "collections": [
      {
        "id": "collection_123",
        "name": "Best Characters",
        "item_count": 25,
        "created_at": "2026-02-28T10:00:00Z",
        "modified_at": "2026-02-28T12:00:00Z"
      }
    ]
  }
}

---

Create/Update Collection

POST /mjr/am/collections/create
POST /mjr/am/collections/update

Request Body (Create):

{
  "name": "Best Characters",
  "items": [
    {
      "asset_id": "asset_123",
      "scope": "output"
    }
  ]
}

Request Body (Update):

{
  "collection_id": "collection_123",
  "name": "Updated Name",
  "items": [...],
  "add_items": [...],    // Items to add
  "remove_items": [...]  // Items to remove
}

Response:

{
  "ok": true,
  "data": {
    "collection_id": "collection_123",
    "name": "Updated Name",
    "item_count": 30
  }
}

---

Delete Collection

POST /mjr/am/collections/delete

Request Body:

{
  "collection_id": "collection_123"
}

Response:

{
  "ok": true,
  "data": {
    "collection_id": "collection_123",
    "deleted": true
  }
}

Note: Does not delete assets, only the collection definition.

---

List Custom Roots

GET /mjr/am/custom-roots

Response:

{
  "ok": true,
  "data": {
    "roots": [
      {
        "id": "root_123",
        "path": "/path/to/custom/dir",
        "name": "Custom Directory",
        "added_at": "2026-02-28T10:00:00Z"
      }
    ]
  }
}

---

Add Custom Root

POST /mjr/am/custom-roots/add

Request Body:

{
  "path": "/path/to/custom/dir",
  "name": "Custom Directory"
}

Response:

{
  "ok": true,
  "data": {
    "root_id": "root_123",
    "path": "/path/to/custom/dir",
    "added": true
  }
}

---

Remove Custom Root

POST /mjr/am/custom-roots/remove

Request Body:

{
  "root_id": "root_123"
}

Response:

{
  "ok": true,
  "data": {
    "root_id": "root_123",
    "removed": true
  }
}

---

Viewer & Metadata

Viewer Info

GET /mjr/am/viewer/info

Query Parameters:

Example:

GET /mjr/am/viewer/info?asset_id=asset_123

Response:

{
  "ok": true,
  "data": {
    "asset_id": "asset_123",
    "filename": "fantasy_character.png",
    "type": "image",
    "width": 1024,
    "height": 1536,
    "metadata": {
      "prompt": "A fantasy character...",
      "model": "SDXL",
      "workflow_minimap": { ... }
    }
  }
}

---

Download & Export

Download Asset

GET /mjr/am/download

Query Parameters:

Example:

GET /mjr/am/download?asset_id=asset_123

Response: File stream with appropriate Content-Type and Content-Disposition headers.

---

Create Batch ZIP

POST /mjr/am/batch-zip

Request Body:

{
  "asset_ids": ["asset_123", "asset_124", "asset_125"]
}

Response:

{
  "ok": true,
  "data": {
    "token": "zip_token_abc123",
    "expires_at": "2026-02-28T11:00:00Z",
    "download_url": "/mjr/am/batch-zip/zip_token_abc123"
  }
}

---

Download Batch ZIP

GET /mjr/am/batch-zip/{token}

Response: ZIP file stream containing all requested assets.

---

Database Maintenance

Optimize Database

POST /mjr/am/db/optimize

Purpose: Run PRAGMA optimize and ANALYZE for performance.

Response:

{
  "ok": true,
  "data": {
    "optimized": true,
    "duration_ms": 150
  }
}

---

Cleanup Case Duplicates

POST /mjr/am/db/cleanup-case-duplicates

Purpose: Remove historical path-case duplicates (Windows-specific).

Response:

{
  "ok": true,
  "data": {
    "duplicates_removed": 5,
    "kept_canonical": 100
  }
}

---

Force-Delete Database

POST /mjr/am/db/force-delete

Purpose: Emergency recovery for corrupted databases.

Response:

{
  "ok": true,
  "data": {
    "deleted": true,
    "reinitialized": true,
    "rescan_triggered": true
  }
}

Note: This endpoint bypasses normal DB-dependent security checks for emergency recovery.

---

Utilities

Date Histogram

GET /mjr/am/date-histogram

Query Parameters:

Example:

GET /mjr/am/date-histogram?month=2026-02&scope=output

Response:

{
  "ok": true,
  "data": {
    "month": "2026-02",
    "days": [
      { "date": "2026-02-01", "count": 50 },
      { "date": "2026-02-02", "count": 75 },
      ...
    ]
  }
}

Purpose: Calendar histogram for date-based filtering UI.

---

Duplicate Alerts

GET /mjr/am/duplicates/alerts

Response:

{
  "ok": true,
  "data": {
    "duplicate_groups": [
      {
        "filename": "image.png",
        "paths": [
          "/path/to/output/image.png",
          "/path/to/output/subfolder/image.png"
        ],
        "count": 2
      }
    ],
    "total_groups": 5,
    "total_duplicates": 10
  }
}

---

Releases Information

GET /mjr/am/releases

Response:

{
  "ok": true,
  "data": {
    "current_version": "2.4.5",
    "branch": "main",
    "latest_release": {
      "version": "2.4.5",
      "date": "2026-04-10",
      "download_url": "https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager/releases/tag/v2.4.5"
    },
    "branches_available": ["main", "dev"],
    "tags_available": ["v2.4.5", "v2.4.4", "v2.4.3", "v2.4.2"]
  }
}

---

Security Notes

CSRF Protection

All state-changing endpoints (POST, PUT, PATCH, DELETE) require:

• X-Requested-With: XMLHttpRequest header, OR
• X-CSRF-Token header with valid token

Authentication

When ComfyUI auth is enabled:

• Write operations require authenticated user
• API token can be used for remote access
• Token sent via X-MJR-Token or Authorization: Bearer

Safe Mode

When Safe Mode is enabled (default):

• Delete operations require MAJOOR_ALLOW_DELETE=1
• Rename operations require MAJOOR_ALLOW_RENAME=1
• Open in folder requires MAJOOR_ALLOW_OPEN_IN_FOLDER=1

Rate Limiting

Expensive endpoints are rate-limited:

• Search: 10 requests/minute per client
• Scan: 5 requests/minute per client
• Batch ZIP: 3 requests/minute per client
• Metadata: 20 requests/minute per client

Client identity based on IP address (or X-Forwarded-For from trusted proxies).

---

Error Responses

Standard Error Format

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": { ... }  // Optional additional context
  }
}

Common Error Codes

---

WebSocket Events

Real-Time Updates

The extension emits ComfyUI API events for real-time updates:

• mjr-asset-added: New asset indexed
• mjr-asset-updated: Asset metadata updated
• mjr-scan-complete: Scan operation completed
• mjr-enrichment-status: Metadata enrichment status
• mjr-db-restore-status: Database restore status

Example (Frontend):

api.addEventListener("mjr-asset-added", (event) => {
  const asset = event.detail;
  // Update UI with new asset
});

---

API Reference Version: 2.0 Last Updated: April 5, 2026 Compatible with Majoor Assets Manager v2.4.4+

Architecture Map

Version: 2.4.5 Last Updated: April 10, 2026

This map is the working reference for backend refactors. It is intentionally short and operational.

Package Responsibilities

• mjr_am_backend/routes
• HTTP surface only.
• Parse request data, apply auth/CSRF/rate-limit guards, call services, map Result payloads.
• route_catalog.py — declarative route registry (RouteRegistration dataclass, CORE + OPTIONAL catalogs).
• mjr_am_backend/routes/core
• Shared route helpers for security, path rules, JSON parsing, responses, and service resolution.
• mjr_am_backend/routes/assets
• Thin compatibility facades re-exporting from features/assets/.
• mjr_am_backend/features
• Business logic and orchestration by domain: index, metadata, collections, browser, health, tags, viewer.
• mjr_am_backend/features/assets
• Asset domain sub-services:
• lookup_service — asset lookups and queries
• download_service — download/streaming logic
• rating_tags_service — ratings, tags, collections
• request_context_service — request parsing and context extraction
• path_resolution_service — root/subfolder/path resolution
• delete_service — asset deletion
• rename_service — asset renaming
• filename_validator — filename validation rules
• models — shared data models
• service — thin compatibility facade
• mjr_am_backend/adapters
• Boundary code for SQLite, filesystem watchers, external tools, and other integration points.
• mjr_am_backend/adapters/db
• sqlite_facade.py — main entry point for DB access (~1900 L)
• sqlite_connections.py — connection pool, pragmas, acquire/release
• sqlite_execution.py — query execution, timeout, retry, batch
• sqlite_lifecycle.py — transactions, reset, WAL, Windows file-handle management
• sqlite_recovery.py — malformed recovery, FTS rebuild, schema repair
• schema.py (331 L) + schema_sql.py, schema_fts.py, schema_vec.py — DDL and migration
• connection_pool.py, db_recovery.py, transaction_manager.py — lower-level helpers
• mjr_am_shared
• Shared result types, error definitions, logging, time helpers, and cross-cutting utilities.

Frontend

• Vue 3 + Pinia for all major UI surfaces (grid, sidebar, feed, context menus, settings).
• js/vue/ — Vue components and stores.
• js/features/ — feature-scoped JS modules.
• js/stores/ — Pinia stores.
• Imperative runtime services remain for viewer, DnD, and ComfyUI integration (by design).

Request Flow

UI action -> route handler -> route/core helper -> feature service -> adapter -> DB/filesystem/tool -> Result response -> UI mapping

Rules:

• Routes do not decide filesystem or security policy locally.
• Services own business rules and orchestration.
• Adapters isolate external side effects.
• security.py is the single policy entry point for auth, write access, safe mode, trusted proxies, and CSRF.

Watcher And Index Flow

Filesystem event -> watcher scope/runtime -> index orchestration -> DB update -> UI refresh event

Hot zones:

• watcher lifecycle and scope resolution
• reset/rebuild orchestration
• metadata probing and vector backfill
• live viewer synchronization

These zones should be refactored behind stable service facades before adding new behavior.

Security Rules

• Public API base stays /mjr/am/*.
• Backend returns structured Result payloads for expected errors.
• Safe mode is enabled by default.
• Remote write remains denied without a valid token.
• Loopback write is allowed by default in the current compatibility model unless MAJOOR_REQUIRE_AUTH=1 is set.

Naming And Internal API Conventions

• Public internal APIs should be thin, stable facades under features/ or routes/core/.
• Route modules may import facades and helpers, but should not directly orchestrate storage internals across multiple subsystems.
• New security-sensitive mutations must call shared security and path helpers instead of duplicating checks.

Audit — Réactivité grille, chargement, cache & premier lancement

Date : 2026-04-22

Périmètre

Audit ciblé sur le pipeline de rendu de la grille d'assets : ouverture du panneau, premier chargement, switch de scope, cache snapshot, événements temps réel et pagination. Objectif : suppression des doubles chargements, des sérialisations bloquantes et des relances concurrentes pour obtenir un comportement strictement live.

Fichiers principaux audités :

• js/vue/composables/useGridLoader.js
• js/vue/composables/useVirtualGrid.js
• js/features/grid/gridApi.js
• js/features/grid/StackGroupCards.js
• js/features/panel/panelRuntime.js
• js/features/panel/panelGridEventBindings.js
• js/features/panel/panelSettingsSync.js
• js/features/panel/controllers/scopeController.js
• js/features/panel/controllers/gridController.js
• js/features/runtime/registerRealtimeListeners.js
• js/features/runtime/entryUiRegistration.js
• js/vue/components/grid/VirtualAssetGridHost.vue

---

1. Constats

1.1 [HIGH] Double hydratation snapshot lors du switch de scope (corrigé)

Symptôme : Pour chaque switch de scope avec query == "*", la même hydratation depuis GRID_SNAPSHOT_CACHE était jouée deux fois consécutivement (appendAssets + setItems + finalizeLoad), provoquant un re-render perceptible et une charge CPU inutile.

Chaîne d'appel :

1. scopeController.setScope → onBeforeReload → prepareGridForScopeSwitch()

appelle void hydrateFromSnapshot(...) (synchrone interne, peuple state.assets).

2. Le contrôleur enchaîne await reloadGrid() → loadAssets().
3. loadAssets() détecte deferVisualResetUntilNextPage = true (assets visibles)

et entre dans le fast-path snapshot qui appelle hydrateFromSnapshot() une seconde fois sur la même clé.

Correctif : Le hook hydrateFromSnapshot marque maintenant la clé hydratée sur l'état (state._mjrLastHydrateKey / _mjrLastHydrateAt). Le fast-path de loadAssets() court-circuite l'appel si la dernière hydratation porte sur la même clé et date de moins de 1500 ms ; il se contente de planifier un prefetch de la page suivante.

Fichier : useGridLoader.js

---

1.2 [MED] Persistance sessionStorage synchrone à chaque page (corrigé)

Symptôme : rememberSnapshot() est appelé à chaque page chargée (loadNextPage) et à chaque réussite d'hydratation. Chaque appel chaîne pruneGridSnapshotCache() puis JSON.stringify de jusqu'à 8 snapshots × 800 assets ≈ plusieurs Mo de payload, sur le main thread, et un storage.setItem. Pendant un scroll soutenu sur 7000+ assets, ce coût se répète à chaque page, dégradant la fluidité de la pagination.

Correctif : persistGridSnapshotsToStorage() devient un debounce 500 ms au-dessus de persistGridSnapshotsToStorageNow(). dispose() flush explicitement avant unload pour ne perdre aucun snapshot.

Fichier : useGridLoader.js

---

1.3 [MED] Premier lancement : cache affiché sans rafraîchissement de fond (corrigé)

Symptôme : Lors d'une ouverture du panneau avec snapshot disponible (didHydrateFromSnapshot == true), panelRuntime.js court-circuite reloadGrid() et n'émet aucune requête API. L'utilisateur voit donc des cartes potentiellement vieilles de 30 minutes (TTL snapshot) jusqu'au prochain événement temps réel ou interaction. Le comportement attendu est live.

Correctif : panelRuntime.js planifie maintenant un reloadGrid() silencieux 200 ms après l'ouverture lorsque l'hydrate snapshot a réussi. Les cartes en cache restent visibles (preserve-visible-until-ready) jusqu'à l'arrivée de la première page fraîche.

Fichier : panelRuntime.js

---

1.4 [LOW] Multiples upserts par asset généré

Constat : Pour un même asset issu d'une génération, jusqu'à trois événements temps réel arrivent en cascade :

Chaque upsert passe par upsertAssetNow() qui coalesce via queueMicrotask, mais comme les WebSocket arrivent dans des macrotâches distinctes, on obtient typiquement 3 vg.setItems(state.assets) par asset.

Statut : Comportement actuellement acceptable. La coalescence microtâche gère les bursts simultanés (une seule génération de 5 cartes → 1 setItems). Les 3 événements espacés mettent à jour des champs successifs (placeholder → métadonnées → enrichissement). Aucune action immédiate.

Recommandation future : ajouter un debounce 50 ms par assetId côté upsertLiveAssetIntoGrid si une régression de fluidité est constatée.

Fichier : registerRealtimeListeners.js

---

1.5 [LOW] MIN_LOADING_SKELETON_MS artificiellement bloque les chargements rapides

Constat : loadNextPage() impose un await waitMs(50 - elapsed) quand la page revient en moins de 50 ms (cas snapshot ou cache HTTP chaud). Ajoute jusqu'à 50 ms de latence perçue.

Statut : Conservé volontairement pour éviter le clignotement du skeleton. Pas de modification.

---

1.6 [INFO] Sync dataset redondant entre onBeforeReload et runReloadOnce

Constat : panelRuntime.onBeforeReload écrit gridContainer.dataset.mjrScope/Subfolder/..., puis quelques µs plus tard gridController.runReloadOnce ré-écrit le même set. Pas de risque, légère duplication. À fusionner lors d'un refactor mais sans urgence.

---

1.7 [INFO] Nettoyage cache stack/dup au switch de scope

Vérifié : prepareGridForScopeSwitch() appelle bien disposeStackGroupCards() (corrige BUG #1 mémoire). Les états state.stemMap / state.filenameCounts sont quant à eux réinitialisés via resetAssetCollectionsState() au moment où la première page de la nouvelle scope arrive (cf. loadNextPage if (deferVisualResetUntilNextPage)). OK.

---

1.8 [INFO] Early-fetch output:*:mtime_desc

Vérifié : startEarlyFetch() est idempotent (clé + TTL 15 s + AbortController unique). consumeEarlyFetch() purge l'entrée à la consommation. La promesse est rejetée proprement sur pagehide. Comportement correct.

---

1.9 [INFO] VirtualAssetGridHost — gating première mesure

Vérifié : hasMeasuredHostWidthOnce empêche le premier paint avant que ResizeObserver ait livré la largeur de l'hôte (corrige le double-render historique). OK.

---

2. Synthèse des corrections appliquées

---

3. Pistes restantes (non bloquantes)

1. Coalescer les 3 événements NEW_GEN_OUTPUT / ASSET_ADDED / ASSET_INDEXED

par assetId sur 50 ms côté registerRealtimeListeners pour réduire le nombre de setItems lors d'une rafale de générations.

2. *Mutualiser la mise à jour des dataset.mjr** entre onBeforeReload et

runReloadOnce dans un helper unique.

3. Diagnostic cache : exposer window.__MJR_GRID_CACHE_STATS__ (size,

hits, misses) en mode debug pour profiler le ratio cache/fetch.

4. Snapshot par scope plus fin : actuellement la persistance écrit toutes

les snapshots ; possible d'écrire uniquement la dernière modifiée (delta write) si la taille devient gênante.

---

4. Validation

• get_errors sur les fichiers modifiés : aucune erreur.
• Aucun changement d'API publique : loadAssets / reloadGrid /

prepareGridForScopeSwitch conservent leur signature.

• Tests à exécuter : vitest sur js/tests/grid_loader_*.vitest.mjs.

Contributing to Majoor Assets Manager

Thank you for your interest in contributing to ComfyUI-Majoor-AssetsManager! This guide will help you set up your development environment, understand our coding standards, and submit quality contributions.

---

Table of Contents

• Development Setup
• Project Structure
• Coding Standards
• Testing
• Submitting Contributions
• Git Workflow
• Code Quality Gate
• Documentation
• Getting Help

---

Development Setup

Prerequisites

• Python: 3.10 - 3.13 (3.14 not yet supported)
• Node.js: 18+ (LTS recommended)
• Git: 2.30+
• ComfyUI: >= 0.13.0 (running instance for testing)

Quick Start

# 1. Clone the repository
git clone https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager.git
cd ComfyUI-Majoor-AssetsManager

# 2. Install Python dependencies
pip install -r requirements.txt

# For AI/vector features (optional):
pip install -r requirements.txt -r requirements-vector.txt

# For development tooling (optional but recommended):
pip install -r requirements-dev.txt

# 3. Install Node dependencies
npm install

# 4. Install Git hooks (pre-commit, pre-push quality gates)
npm run hooks:install

# 5. Build frontend (if making JS/Vue changes)
npm run build

Development Workflow

# Watch mode for frontend development (auto-rebuild)
npm run build:watch

# Run Python tests
pytest

# Run frontend tests
npm run test:js

# Run quality checks (linters, type checkers, security scanners)
npm run quality

# Python-only quality check (faster)
npm run quality:py

# Fix linting issues
npm run lint:py:fix   # Python
npm run lint:js:fix   # JavaScript
npm run format        # Prettier

---

Project Structure

majoor-assetsmanager/
├── __init__.py                    # ComfyUI extension entrypoint
├── mjr_am_backend/                # Python backend (aiohttp routes + features)
│   ├── routes/                    # HTTP route handlers
│   ├── features/                  # Business logic (search, index, AI, etc.)
│   └── adapters/                  # External system adapters (DB, FS, tools)
├── mjr_am_shared/                 # Shared utilities (types, errors, logging)
├── js/                            # Frontend source (Vue 3 + vanilla JS)
│   ├── vue/                       # Vue 3 components
│   ├── features/                  # Feature modules (viewer, grid, filters)
│   ├── components/                # Reusable UI components
│   ├── stores/                    # Pinia state management
│   ├── api/                       # Backend HTTP client
│   └── app/                       # Application bootstrap
├── js_dist/                       # Built frontend (Vite output)
├── tests/                         # Python tests (pytest)
│   ├── backend/                   # Backend unit/integration tests
│   ├── features/                  # Feature tests
│   └── security/                  # Security tests
├── docs/                          # Documentation
│   └── adr/                       # Architecture Decision Records
├── scripts/                       # Development/CI scripts
└── plugins/                       # Plugin system examples

Key Architecture Principles

1. Backend: Routes → Features → Adapters (clean separation of concerns)
2. Frontend: Vue 3 owns major UI surfaces; imperative runtime bridges are explicit and limited
3. State: Pinia stores own UI state; localStorage for persistence
4. Security: Safe mode by default; write/delete operations require explicit opt-in
5. Error Handling: Result[T] pattern everywhere — no exceptions bubble to UI

See <code>docs/ARCHITECTURE_MAP.md</code> and <code>docs/adr/</code> for detailed design decisions.

---

Coding Standards

Python

• Style: Follow Black formatting (line length: 100)
• Linting: Ruff with rules in pyproject.toml
• Type Checking: MyPy + Pyright (standard mode)
• Imports: Organized by Ruff I rule (isort-compatible)
• Error Handling: Use Result[T] from mjr_am_shared/result.py — never raise to UI
• Security: Never import ComfyUI/server.py (see ADR-002)

Example:

from mjr_am_shared.result import Result, Ok, Err

def process_asset(asset_id: str) -> Result[dict]:
    try:
        # ... processing logic
        return Ok({"status": "success", "id": asset_id})
    except Exception as e:
        return Err(f"Failed to process asset {asset_id}: {e}")

JavaScript/Vue

• Style: ESLint + Prettier (config in eslint.config.mjs, .prettierrc)
• Framework: Vue 3 Composition API with <script setup>
• State: Pinia stores for reactive state; no global mutable objects
• Testing: Vitest with Happy-DOM for component tests
• Naming: camelCase for variables/functions, PascalCase for Vue components

Example:

<script setup>
import { ref, computed } from 'vue'
import { usePanelStore } from '../../stores/usePanelStore.js'

const props = defineProps({
  asset: { type: Object, required: true }
})

const panelStore = usePanelStore()
const isSelected = computed(() =>
  panelStore.selectedIds.includes(props.asset.id)
)
</script>

Commits

• Use Conventional Commits format:

  feat: add multi-pin support in Floating Viewer
  fix: prevent timeout leak in Card.js
  docs: update API reference with vector endpoints

• Keep commits focused and atomic (one logical change per commit)
• Write clear, descriptive messages (explain "why", not "what")

---

Testing

Backend (Python)

# Run all tests
pytest

# Run with coverage
pytest --cov=mjr_am_backend --cov-report=html

# Run specific test file
pytest tests/features/test_sampler_tracer_extra.py

# Run with timeout
pytest --timeout=30

Test organization:

• tests/backend/ — Backend unit/integration tests
• tests/features/ — Feature-specific tests (geninfo parser, metadata extraction)
• tests/security/ — Security tests (rate limiting, auth)
• tests/database/ — Database schema and migration tests

Frontend (JavaScript/Vue)

# Run all tests
npm run test:js

# Run with coverage
npm run test:js:coverage

# Watch mode
npm run test:js:watch

Test organization:

• js/tests/ — Vitest test files
• Test files named *.vitest.mjs
• Cover: composables, utilities, security-critical modules

Coverage Thresholds

Note: These are minimum thresholds. Security-critical code should have 100% coverage.

---

Submitting Contributions

Before You Start

1. Check existing issues: See if someone else is working on your idea
2. Open an issue: For features, bugs, or significant changes
3. Discuss approach: For complex changes, propose design in issue comments

Pull Request Process

1. Fork the repository and create your branch from main
2. Make your changes following coding standards
3. Add tests for new features or bug fixes
4. Run quality gate: npm run quality (must pass)
5. Update documentation if behavior changes
6. Submit PR with clear description:
• What changed and why
• How to test the changes
• Any breaking changes or migration steps

PR Checklist

• [ ] Code follows project style guide
• [ ] Self-review completed
• [ ] Tests added/updated
• [ ] Quality gate passes (npm run quality)
• [ ] Documentation updated
• [ ] Commit messages are clear and conventional
• [ ] No merge conflicts with target branch

Review Process

Mainters will review your PR and may:

• Request changes (address feedback before merging)
• Approve and merge
• Ask for clarification on implementation choices

---

Git Workflow

Branch Strategy

• main: Stable release branch (always deployable)
• Feature branches: feat/feature-name or fix/bug-name
• Release tags: v2.4.5, v2.5.0, etc. (semantic versioning)

Typical Workflow

# 1. Create feature branch
git checkout main
git pull origin main
git checkout -b feat/add-new-filter

# 2. Make changes and commit
git add .
git commit -m "feat: add resolution filter to asset queries"

# 3. Push and create PR
git push origin feat/add-new-filter

Pre-Push Quality Gate

The pre-push hook automatically runs:

python scripts/run_changed_quality_gate.py

This checks changed files only (faster than full quality gate).

---

Code Quality Gate

The quality gate enforces:

Python Checks

• ✅ UTF-8 text files without BOM
• ✅ Ruff linting (changed files during migration window)
• ✅ MyPy type checking
• ✅ Bandit security linting
• ✅ pip-audit dependency auditing
• ✅ Xenon/Radon complexity checks
• ✅ Backend tests pass

Frontend Checks

• ✅ ESLint passes
• ✅ Prettier formatting
• ✅ Vitest tests pass
• ✅ npm audit passes

Running the Gate

# Full quality gate
npm run quality

# Python only (faster)
npm run quality:py

# Skip tests (for quick checks)
python scripts/run_quality_gate.py --skip-tests

# Tox environment
tox -e quality

Important: The quality gate must pass before PRs are merged.

---

Documentation

When to Update Docs

Update documentation when:

• Adding new features or changing behavior
• Modifying API endpoints or configuration
• Introducing breaking changes
• Fixing bugs that affect user-facing behavior

Documentation Standards

• Language: English (all user-facing docs)
• Format: Markdown (.md files)
• Location: docs/ directory
• Index: Update <code>docs/DOCUMENTATION_INDEX.md</code> for new docs

Types of Documentation

Architecture Decision Records (ADRs)

For significant architectural decisions:

1. Create docs/adr/NNNN-short-title.md
2. Follow ADR template (context, decision, consequences)
3. Reference in docs/adr/README.md

See existing ADRs for examples.

---

Getting Help

Resources

• Documentation: <code>docs/DOCUMENTATION_INDEX.md</code>
• API Reference: <code>docs/API_REFERENCE.md</code>
• Architecture: <code>docs/ARCHITECTURE_MAP.md</code>
• Changelog: <code>CHANGELOG.md</code>

Contact

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions or share ideas

Common Questions

Q: How do I test changes locally?

# Rebuild frontend
npm run build

# Restart ComfyUI (extension loads from js_dist/)
# Test in browser, iterate quickly

Q: Can I add a new dependency?

• Runtime: Must be justified and approved (keep minimal)
• Dev: Easier to approve (testing, linting tools)
• Optional: AI/vector deps in requirements-vector.txt

Q: What if the quality gate fails on CI but passes locally?

• Check Python/Node version differences
• Ensure all files are committed (CI checks entire repo)
• Run npm run quality from clean state

---

Recognition

Contributors are recognized in:

• GitHub contributors page
• Release notes (for significant contributions)
• This file (optional, add your name below)

Contributors

• MajoorWaldi — Original creator and lead maintainer
• [Your name here — submit a PR to add yourself!]

---

License

By contributing, you agree that your contributions will be licensed under the project's LICENSE.

Thank you for helping make Majoor Assets Manager better! 🎉

Custom Nodes Reference

Majoor Assets Manager provides two ComfyUI nodes that embed generation timing metadata directly inside saved files. The asset manager's indexing pipeline then reads this metadata automatically.

Source: <code>nodes.py</code>

---

Majoor Save Image 💾

Node name: MajoorSaveImage Category: Majoor Display name: Majoor Save Image 💾

Drop-in replacement for ComfyUI's built-in SaveImage node. Saves PNG files to the standard output directory with generation_time_ms persisted in the PNG text chunks.

Inputs

Hidden Inputs

Metadata Written

Each saved PNG contains the following text chunks:

Output

Returns a UI result with the list of saved images (filename, subfolder, type) for ComfyUI's preview system.

Example Usage

1. Connect any image output to the images input
2. Optionally set a custom filename_prefix
3. Leave generation_time_ms at -1 for automatic timing
4. The node saves PNGs to ComfyUI/output/ with full metadata

---

Majoor Save Video 🎬

Node name: MajoorSaveVideo Category: Majoor Display name: Majoor Save Video 🎬

Saves a VIDEO input or a batch of IMAGE frames as a video file. Uses PyAV for MP4 encoding (same approach as ComfyUI's native SaveVideo node) and Pillow for GIF/WebP.

Inputs

Hidden Inputs

Input Resolution

At least one of images or video must be connected:

• video input (priority): frame tensor, frame rate, and audio are extracted via video.get_components(). The frame_rate widget is ignored.
• images input (fallback): frames are taken from the IMAGE batch, and frame_rate / audio widgets are used.
• Neither connected: the node produces no output.

Metadata Written

MP4 (h264)

Metadata is embedded directly in the MP4 container using PyAV with movflags=use_metadata_tags:

These tags are readable by FFProbe (ffprobe -show_format_tags) and ExifTool.

GIF / WebP

Animated GIF and WebP formats do not support arbitrary metadata. When save_first_frame is enabled (default), a PNG sidecar is saved alongside the animation with full metadata in its text chunks. The asset manager indexes this sidecar automatically.

Video Encoding Details

• Codec: libx264, pixel format yuv420p
• Quality: controlled by crf (default 19)
• Audio: AAC codec, supports mono/stereo/5.1 layouts
• Frame rate: stored as an exact fraction for precision

Output

Returns a UI result with the saved video file(s) for ComfyUI's preview system.

Example Usage

From IMAGE batch:

1. Connect a batch of images to images
2. Set format to mp4 (h264)
3. Adjust frame_rate and crf as needed
4. The node saves an MP4 to ComfyUI/output/

From VIDEO input:

1. Connect a VIDEO output to video
2. The node uses the video's native frame rate and audio
3. Set format and crf to control encoding

---

Auto-Detection of generation_time_ms

Both nodes support automatic generation time measurement. When generation_time_ms is set to -1 (default), the node computes the elapsed time by reading the prompt start time from Majoor's runtime_activity module.

How It Works

1. When ComfyUI starts executing a prompt, runtime_activity records time.monotonic() as last_started_at
2. When the save node runs, it computes (time.monotonic() - last_started_at) * 1000 to get milliseconds
3. This value is written into the file metadata

Manual Override

Connect an INT value to generation_time_ms (any value ≥ 0) to override automatic detection. This is useful for:

• Measuring only part of a workflow
• Importing timing from external sources
• Testing and debugging

---

Extraction Pipeline

When assets are indexed by Majoor Assets Manager, generation_time_ms is extracted through the following chain:

PNG Files

1. read_png_text_chunks() reads the generation_time_ms text chunk → PNG:Generation_time_ms
2. _merge_png_exif() merges it into the EXIF data dict
3. _apply_rating_tags_and_generation_time() extracts the integer value → metadata["generation_time_ms"]
4. _best_effort_generation_time_ms() finds it at the top level and returns it for DB storage

MP4 Files

1. FFProbe reads the container format tags (including generation_time_ms)
2. apply_video_ffprobe_fields() extracts it from format.tags.generation_time_ms
3. _best_effort_generation_time_ms() finds it and returns it for DB storage

Fallback Behavior

When the Majoor save nodes are not used (e.g., standard SaveImage or third-party nodes), the asset manager falls back to:

• EXIF DateTimeOriginal / CreateDate for generation_time (date-based, not duration)
• Prompt graph analysis for workflow metadata
• No generation_time_ms is stored (column remains NULL)

Database Maintenance

Version: 2.4.5 Last Updated: April 7, 2026

Majoor Assets Manager stores its index in an SQLite database. By default this is at <output>/_mjr_index/assets.sqlite, but the index directory can be relocated to any local path — useful when your output folder is on a network share. This document covers the maintenance tools available in the UI, the recovery procedures for corruption scenarios, and how to configure the index directory.

Recent highlights: Improved corruption detection, automatic health monitoring, and safer rebuild flows.

Configuring the Index Directory

By default the index lives next to your assets at <output>/_mjr_index/. You can move it to any local path without touching your asset files.

Why you might want to relocate

• Network drives (NAS/SMB/CIFS): SQLite relies on OS-level file locking. Many NAS/SMB implementations do not support these locks reliably, which can cause "database is locked" errors under concurrent access. Moving the index to a fast local SSD while keeping assets on the NAS eliminates this class of error entirely.
• Separate disk for performance: Keep assets on a large slow HDD and the index/DB on a fast SSD.
• Shared ComfyUI install, separate indexes: Multiple users on the same machine can each point to their own index directory.

How to configure

Option 1 — UI (recommended, survives reinstalls):

1. Open Settings → Majoor Assets Manager → Advanced and search for path if needed.
2. Locate Index Database Directory.
3. Enter the full path to the desired directory (it will be created if it does not exist).
4. Save. A toast confirms the change and reminds you to restart ComfyUI.
5. Restart ComfyUI. A fresh scan runs on startup.

[Index directory override in Majoor settings]

The same section also exposes Generation Output Directory when you need to override the ComfyUI output folder independently from the database location.

The UI persists the path in a sidecar file .mjr_index_directory_override next to the extension root. This file takes precedence over the default on every startup.

Option 2 — Environment variable:

Set either MJR_AM_INDEX_DIRECTORY or MAJOOR_INDEX_DIRECTORY in the environment that launches ComfyUI:

:: Windows — batch launcher
set MJR_AM_INDEX_DIRECTORY=C:\mjr_index
python main.py

# Linux/macOS — shell launcher
export MJR_AM_INDEX_DIRECTORY=/var/local/mjr_index
python main.py

Env var overrides the sidecar file and the default. Restart ComfyUI after changing it.

Priority order (highest wins):

1. MJR_AM_INDEX_DIRECTORY or MAJOOR_INDEX_DIRECTORY environment variable
2. .mjr_index_directory_override sidecar file (written by the UI)
3. Default: <output_directory>/_mjr_index/

What the index contains

The index directory holds:

After changing the index directory

1. Restart ComfyUI to apply the new path.
2. A fresh scan starts automatically.
3. Ratings, tags, and AI vectors from the old database are not automatically migrated.
• To migrate: stop ComfyUI, copy the .sqlite files to the new directory, then restart.
4. The old _mjr_index directory is not deleted automatically.

---

Buttons in the Status Panel

Open the Assets Manager panel and expand the Index Status section. Two action buttons appear at the bottom:

Reset Index

The Reset index button calls POST /mjr/am/scan/reset with flags to clear assets, metadata, FTS index, and scan journal, then triggers a full rescan.

If the database is corrupted, the reset will fail because security-preference queries cannot execute on a malformed database. When this happens:

• The status dot turns red.
• A toast appears: "Reset failed -- database is corrupted. Use the Delete DB button to force-delete and rebuild."

Delete DB (Emergency Recovery)

The Delete DB button calls POST /mjr/am/db/force-delete. It is designed to work even when the database is completely unreadable.

How it works

1. CSRF check only -- no database-dependent security queries are run.
2. Adapter reset (fast path) -- tries db.areset() first. If this succeeds the database is wiped through the adapter and a rescan starts immediately.
3. Manual file deletion (fallback) -- if the adapter reset fails (typical for severe corruption):
• Calls db.close() to release connections.
• Runs gc.collect() twice with a short delay to release Windows file handles.
• Deletes assets.sqlite, assets.sqlite-wal, assets.sqlite-shm, and assets.sqlite-journal with up to 6 retries per file.
4. Re-initialization -- creates a fresh database with all tables, indexes, and triggers.
5. Background rescan -- triggers a full non-incremental scan of the output directory.

Confirmation dialog

Before proceeding, the UI first asks whether existing AI vectors should be kept, then shows a simple confirmation dialog in the ComfyUI Manager style for the selected action.

What is lost

• Star ratings
• Custom tags
• Cached metadata (prompts, models, generation parameters)
• Scan journal / history

What is preserved

• Original image/video/audio files (never touched)
• Collections (stored as separate JSON files in _mjr_index/collections/)
• Custom roots configuration (_mjr_index/custom_roots.json)
• All ComfyUI settings (stored in localStorage)

Automatic Corruption Detection

The status polling loop (every few seconds) checks health counters via GET /mjr/am/health/counters. If the response error contains keywords like "malformed", "corrupt", or "disk image":

• The status dot turns red.
• The status text shows "Database is corrupted" with a hint to use the Delete DB button.
• A one-time toast notification appears with the same guidance.

The toast fires only once per session to avoid spamming. It resets after a successful Delete DB operation.

Database Optimize

An additional endpoint POST /mjr/am/db/optimize runs PRAGMA optimize and ANALYZE on the database. This is useful after large scans or bulk deletes to keep query performance optimal. It is best-effort and never throws errors to the UI.

Manual Recovery

If the Delete DB button reports that files could not be deleted (another process holds a lock):

1. Stop ComfyUI completely.
2. Navigate to <output>/_mjr_index/.
3. Delete assets.sqlite and any sibling files (-wal, -shm, -journal).
4. Restart ComfyUI.
5. The database will be recreated automatically on startup and a scan will populate it.

Related Files

Environment Variables

Dependency Policy

Date: 2026-04-09

Goal

Keep one explicit dependency contract per use case and avoid drift between packaging metadata, manual installs, and CI tooling.

Source Of Truth

• requirements.txt is the primary dependency source of truth for the project.
• requirements.txt is also the default runtime install contract for the extension.
• requirements-vector.txt extends runtime with optional AI/vector dependencies.
• requirements-dev.txt is the contributor tooling layer for tests, linting, typing, and security checks.
• pyproject.toml mirrors published metadata and optional dependency groups for packaging, but does not replace requirements.txt as the source of truth used by users and CI.

Dependency Roles

Runtime

Put a dependency in requirements.txt only if the extension needs it for normal backend operation.

Examples:

• aiohttp
• aiosqlite
• pillow
• send2trash

Optional AI / Vector

Put a dependency in requirements-vector.txt only if it is required for optional AI, vector search, captioning, clustering, or related enrichment features.

This file must include -r requirements.txt so it always layers on top of the runtime baseline.

Dev / Contributor Tooling

Put a dependency in requirements-dev.txt only if it is used to develop, test, lint, type-check, or audit the project locally or in CI.

Examples:

• pytest
• ruff
• mypy
• bandit
• pip-audit

Dev tools must not be added to requirements.txt just because CI uses them.

Update Rules

When adding or changing a dependency:

1. Decide whether it is runtime, vector, or dev.
2. Update requirements.txt first when the dependency affects the main project baseline.
3. Update the matching extension file when the dependency is optional or contributor-only.
4. Mirror the change in pyproject.toml when it affects published metadata.
5. Update docs if the install story or contributor workflow changed.
6. Run the relevant tests or quality checks for the impacted area.

CI And Quality Gate Expectations

• Runtime security auditing targets requirements.txt.
• Contributor tooling is installed from requirements-dev.txt for local development and quality workflows.
• Optional AI/vector installs remain opt-in and must not become implicit in the default setup.

Non-Goals

• No hidden dependency source in ad hoc scripts.
• No “install everything always” default for end users.
• No divergence between README instructions and the actual files used by installs.

Quick Commands

# Runtime only
pip install -r requirements.txt

# Runtime + optional AI/vector features
pip install -r requirements.txt -r requirements-vector.txt

# Contributor tooling
pip install -r requirements-dev.txt

Majoor Assets Manager - Drag & Drop Guide

Version: 2.4.5 Last Updated: April 5, 2026

Overview

The Majoor Assets Manager provides seamless drag and drop functionality that integrates with both ComfyUI and your operating system. This guide covers all aspects of drag and drop operations within the extension.

Recent highlights: Audio file staging support, improved multi-select ZIP creation, and better node compatibility detection.

Drag to ComfyUI Canvas

Basic Drag Operation

1. Select one or more assets in the Assets Manager
2. Click and hold on an asset card
3. Drag the asset onto the ComfyUI canvas
4. Release the mouse button to drop the asset

Single Asset Drag

• Drag any single asset to the canvas
• The asset path is automatically injected into compatible nodes
• Compatible nodes include LoadImage, LoadLatent, and similar input nodes
• The asset is staged for immediate use in your workflow

Multiple Asset Drag

• Select multiple assets using Ctrl/Cmd+click or Shift+click
• Drag any selected asset to the canvas
• Multiple file paths are handled appropriately
• Some nodes support multiple inputs, others will use the first path

Node Compatibility

The system intelligently identifies compatible nodes:

Image Input Nodes

• LoadImage: Accepts image file paths
• LoadImageMask: For mask images
• PreviewImage: For direct preview
• LoadLatent: For latent files

Video Input Nodes

• LoadVideo: For video file paths
• VideoLoad: For various video formats

Workflow Input Nodes

• LoadWorkflow: For workflow files
• ImportWorkflow: For external workflow files

Staging Mechanism

• Assets are staged temporarily when dragged to canvas
• Paths are injected into appropriate input fields
• No permanent changes to workflow until execution
• Allows for experimentation without committing to changes

Drag to Operating System

Single File Drag

1. Select an asset in the Assets Manager
2. Click and drag the asset outside the browser window
3. Drop onto your file explorer, desktop, or another application
4. The original file is transferred to the destination

Multiple File Drag

1. Select multiple assets using Ctrl/Cmd+click or Shift+click
2. Drag any selected asset outside the browser window
3. A ZIP file is automatically created containing all selected assets
4. Drop the ZIP file onto your destination

ZIP Creation Process

• ZIP files are created on-demand when dragging multiple items
• Files are streamed directly from disk (no temporary copies)
• ZIPs are flat (no directory structure maintained)
• ZIP files are automatically cleaned up after transfer

Protocol Support

The system supports multiple drag protocols:

DownloadURL Protocol

• Used for single file transfers
• Direct file download to destination
• Maintains original filename and extension

text/uri-list Protocol

• Used for multiple file transfers
• Properly formatted URI list for operating system
• Compatible with most file managers and applications

Drag Operations

Starting a Drag

• Click and hold on any asset card for a moment
• A visual indicator appears showing the drag is active
• The cursor changes to indicate drag operation
• Selection remains active during drag

Drag Indicators

• Visual Outline: Selected assets show a highlighted border
• Cursor Change: Cursor changes to indicate drag capability
• Preview: Small preview of dragged asset(s) follows cursor
• Count Display: For multiple selections, shows number of items

Drag Targets

The system recognizes different drag targets:

Valid Targets

• ComfyUI canvas area
• Compatible input nodes
• Browser address bar (downloads)
• File explorer windows
• Desktop
• Email attachments
• Other applications accepting files

Invalid Targets

• Text input fields (unless specifically designed for file drops)
• Non-compatible areas of the interface
• Applications that don't accept the file type

File Transfer Mechanisms

Direct File Transfer

• Single files are transferred directly
• Maintains original file properties
• Preserves embedded metadata
• No quality loss during transfer

Batch ZIP Transfer

• Multiple files are packaged into a ZIP archive
• ZIP created dynamically during drag operation
• No temporary files written to disk
• Automatic cleanup after transfer completion

Streaming Transfer

• Files are streamed directly from disk
• No intermediate copies created
• Memory efficient for large files
• Maintains file integrity during transfer

Filename Collision Indicator

Understanding the Indicator

• When multiple assets share the same filename, the extension badge shows EXT+
• For example: image.png becomes PNG+ when duplicates exist
• Helps identify potential conflicts during drag operations

Handling Collisions

• Collisions don't prevent drag operations
• ZIP files handle duplicate names automatically
• Individual file drops may require manual renaming
• Consider renaming files to avoid confusion

Drag Performance

Optimizations

• Lightweight preview during drag
• Asynchronous file operations
• Memory-efficient streaming
• Responsive interface during drag operations

Performance Considerations

• Large files may take time to initiate transfer
• Multiple large files in ZIP may take longer to create
• Network drives may affect performance
• System resources impact drag responsiveness

Advanced Drag Features

Drag Preview

• Live preview of dragged assets
• Shows thumbnail of the primary dragged item
• Displays count for multiple selections
• Updates in real-time during drag

Drag Validation

• Validates target compatibility before allowing drop
• Provides visual feedback for valid/invalid targets
• Prevents invalid operations
• Shows appropriate cursors for different states

Drag Cancellation

• Cancel drag by releasing over invalid target
• Escape key cancels active drag operation
• Clicking elsewhere cancels drag
• Drag automatically cancels if window loses focus

Integration with Other Features

Selection Integration

• Drag operations work with current selection
• Multiple selections enable batch operations
• Selection filters apply to drag operations
• Search results can be dragged directly

Collection Integration

• Assets from collections can be dragged normally
• Entire collections can be exported via drag
• Collection organization preserved in transfers
• Cross-collection drags work seamlessly

Rating/Tag Integration

• Rated and tagged assets maintain metadata during drag
• Tags and ratings preserved in file transfers (when supported)
• Filtered views can be dragged directly
• Quality indicators visible during drag

Troubleshooting

Common Drag Issues

Drag Not Initiating

• Ensure you're clicking and holding long enough
• Check that the asset is properly selected
• Verify no JavaScript errors in console
• Try refreshing the Assets Manager

Drag Target Not Recognized

• Ensure target application accepts file drops
• Check if target area is actually droppable
• Verify file type compatibility with target
• Try dragging to a different application

ZIP Creation Failure

• Check available disk space
• Verify write permissions to temporary directory
• Ensure no antivirus interference
• Try dragging fewer files at once

File Transfer Problems

• Large files may timeout during transfer
• Network drives may cause delays
• Antivirus software may interfere
• Check file permissions at destination

Browser-Specific Issues

Chrome/Chromium

• May require specific security settings for file downloads
• Extensions might interfere with drag operations
• Incognito mode may behave differently

Firefox

• Security settings may restrict file operations
• Enhanced Tracking Protection might interfere
• Check privacy settings for file handling

Safari

• May require additional permissions for file access
• Security restrictions could limit functionality
• Check website permissions for file handling

Operating System Issues

Windows

• UAC (User Account Control) may interfere
• Antivirus software may block operations
• File permissions may restrict transfers

macOS

• Gatekeeper may restrict file operations
• Privacy settings may limit access
• Sandboxing could affect functionality

Linux

• File permissions are strictly enforced
• Desktop environment may affect drag behavior
• Security modules might restrict operations

Security Considerations

File Access Security

• Drag operations respect file system permissions
• No files can be accessed that the user can't read
• Temporary files are created with restricted permissions
• ZIP files are cleaned up automatically

Cross-Origin Security

• Drag operations confined to same origin
• No cross-site data leakage possible
• File system access limited to allowed directories
• Path validation prevents directory traversal

Malicious File Protection

• No automatic execution of dragged files
• Files transferred in their original form
• No modification during drag operations
• Integrity preserved throughout transfer

Performance Optimization

Large File Handling

• Stream large files instead of loading entirely
• Progress indicators for long operations
• Asynchronous operations to maintain interface responsiveness
• Memory management for multiple large files

Multiple File Optimization

• Efficient ZIP creation algorithms
• Parallel processing where possible
• Memory buffering for optimal performance
• Cleanup operations scheduled appropriately

Interface Responsiveness

• Drag operations don't block UI thread
• Smooth animations during drag
• Immediate feedback for user actions
• Graceful degradation for slower systems

Best Practices

Efficient Drag Operations

• Use multiple selection for batch operations
• Organize assets in collections for easier access
• Use search and filters to find assets quickly
• Verify target compatibility before initiating drag

File Organization

• Maintain consistent naming conventions
• Use collections to group related assets
• Apply tags for easy retrieval
• Regular cleanup of unused assets

Workflow Integration

• Use drag operations to accelerate workflow creation
• Stage frequently used assets in collections
• Leverage drag to canvas for rapid prototyping
• Combine with other Assets Manager features

Performance Tips

• Close unnecessary browser tabs during large operations
• Ensure sufficient system resources
• Use wired connections for network drives
• Regular maintenance of index database

Advanced Usage

Scripted Operations

• Combine drag operations with automation scripts
• Use collections for automated workflows
• Integrate with external tools via file operations
• Batch processing using drag interfaces

Power User Techniques

• Master keyboard shortcuts with drag operations
• Use multiple monitors for efficient transfers
• Leverage search and filters for precise selection
• Combine collections with drag for complex operations

---

Drag & Drop Guide Version: 1.0 Last Updated: April 5, 2026

Floating Viewer — Workflow Sidebar & Run Implementation

Purpose: The Floating Viewer (MFV) includes a lightweight sidebar panel that allows

modifying widgets of selected nodes on the canvas, plus a Run button,

without duplicating or competing with ComfyUI's native "Workflow Overview" panel.

---

1. Design Principles — "Delegate, Don't Duplicate"

---

2. Module Architecture

js/features/viewer/
├── FloatingViewer.js              ← existing (modified _buildToolbar)
├── floatingViewerManager.js       ← existing (added selection bindings)
│
├── workflowSidebar/               ← NEW submodule
│   ├── WorkflowSidebar.js         ← Main component (DOM panel)
│   ├── NodeWidgetRenderer.js      ← Renders node widgets
│   ├── widgetAdapters.js          ← Type → HTML input adapters
│   └── sidebarRunButton.js        ← Run button (queue prompt)

2.1 Dependencies

FloatingViewer
  └─► WorkflowSidebar        (created in _buildToolbar, injected into MFV DOM)
        ├─► NodeWidgetRenderer  (instantiated 1× per displayed node)
        │     └─► widgetAdapters  (pure functions, no state)
        └─► sidebarRunButton    (autonomous button, calls ComfyUI API)

None of these files import from comfyui-frontend directly. Everything goes through the existing bridge: js/app/comfyApiBridge.js.

---

3. Module by Module

---

3.1 WorkflowSidebar.js — Sidebar Panel

Role: Sliding container (slide-in) that opens on the right side of the Floating Viewer.

┌─────────────────────────────────────────────────────┐
│  Majoor Viewer Lite              [⚙] [▶ Run] [✕]   │  ← header + toolbar
├────────────────────┬────────────────────────────────┤
│                    │  Workflow Sidebar               │
│   Viewer Content   │  ┌────────────────────────────┐ │
│   (image/video)    │  │ KSampler              [📍] │ │
│                    │  │  seed   [156680208700286]   │ │
│                    │  │  steps  [20]                │ │
│                    │  │  cfg    [8.0]               │ │
│                    │  │  sampler [euler ▾]          │ │
│                    │  │  scheduler [normal ▾]       │ │
│                    │  │  denoise [1.00]             │ │
│                    │  ├────────────────────────────┤ │
│                    │  │ CLIP Text Encode       [📍] │ │
│                    │  │  text  [beautiful sce...]   │ │
│                    │  └────────────────────────────┘ │
└────────────────────┴────────────────────────────────┘

Public API

class WorkflowSidebar {
  constructor({ hostEl, onClose })
  show()           // slide-in, reads current selection
  hide()           // slide-out
  toggle()
  refresh()        // re-reads app.canvas.selected_nodes and re-renders
  get isVisible()
  destroy()
}

How to read selected nodes

The pattern already exists in NodeStreamController.js:

import { getComfyApp } from "../../../app/comfyApiBridge.js";

function getSelectedNodes() {
  const app = getComfyApp();
  const selected = app?.canvas?.selected_nodes
                ?? app?.canvas?.selectedNodes
                ?? null;
  if (!selected) return [];
  if (Array.isArray(selected)) return selected.filter(Boolean);
  if (selected instanceof Map) return Array.from(selected.values());
  if (typeof selected === "object") return Object.values(selected);
  return [];
}

How to listen to selection changes

The pattern exists in LiveStreamTracker.js:

const canvas = app.canvas;
const origSelected = canvas.onNodeSelected;
const origSelChange = canvas.onSelectionChange;

canvas.onNodeSelected = function (node) {
  origSelected?.call(this, node);
  sidebar.refresh();  // ← our hook
};

canvas.onSelectionChange = function (selectedNodes) {
  origSelChange?.call(this, selectedNodes);
  sidebar.refresh();  // ← our hook
};

Important: These hooks must be properly attached/detached when opening/closing

the sidebar to avoid leaks. We use the same chained pattern as LiveStreamTracker.

---

3.2 NodeWidgetRenderer.js — Node Rendering

Role: For a given LGraphNode, iterates over node.widgets and generates a corresponding HTML form.

Information available on a ComfyUI widget

node.widgets.forEach(widget => {
  widget.name       // "seed", "steps", "cfg", "sampler_name" …
  widget.type       // "number", "combo", "text", "toggle", "IMAGEUPLOAD" …
  widget.value      // current value
  widget.options     // { min, max, step, values: [...] }  (for combo/number)
  widget.callback   // function(value) — to call after write
});

Generated DOM structure

<section class="mjr-ws-node" data-node-id="3">
  <div class="mjr-ws-node-header">
    <span class="mjr-ws-node-title">KSampler</span>
    <button class="mjr-icon-btn mjr-ws-locate" title="Locate on canvas">
      <i class="pi pi-map-marker"></i>
    </button>
  </div>
  <div class="mjr-ws-node-body">
    <!-- widgets rendered by widgetAdapters -->
  </div>
</section>

Locating a node on the canvas

function locateNode(node) {
  const app = getComfyApp();
  const canvas = app?.canvas;
  if (!canvas || !node) return;
  // Center view on node
  canvas.centerOnNode?.(node);
  // Fallback LiteGraph
  if (!canvas.centerOnNode && canvas.ds) {
    canvas.ds.offset[0] = -node.pos[0] - node.size[0] / 2 + canvas.canvas.width / 2;
    canvas.ds.offset[1] = -node.pos[1] - node.size[1] / 2 + canvas.canvas.height / 2;
    canvas.setDirty(true, true);
  }
}

---

3.3 widgetAdapters.js — Widget → HTML Input Conversion

File of pure functions, no state. Each adapter returns an HTMLElement.

Writing to a ComfyUI widget

function writeWidgetValue(widget, newValue) {
  if (widget.type === "number") {
    const n = Number(newValue);
    if (Number.isNaN(n)) return false;
    const { min = -Infinity, max = Infinity } = widget.options ?? {};
    widget.value = Math.min(max, Math.max(min, n));
  } else {
    widget.value = newValue;
  }
  // Notify ComfyUI that widget changed
  widget.callback?.(widget.value);
  // Mark canvas dirty for visual refresh
  const app = getComfyApp();
  app?.canvas?.setDirty?.(true, true);
  return true;
}

This pattern is identical to the one already used in DragDrop.js for dropping

media on nodes — nothing is reinvented.

---

3.4 sidebarRunButton.js — Run Button

Role: Single button that triggers POST /prompt using ComfyUI API.

Option A — Via app object (recommended)

import { getComfyApp } from "../../../app/comfyApiBridge.js";

async function queueCurrentPrompt() {
  const app = getComfyApp();
  if (!app) return { ok: false, error: "ComfyUI app not ready" };

  // graphToPrompt() serializes current workflow into executable payload
  const promptData = await app.graphToPrompt();
  if (!promptData?.output) return { ok: false, error: "Empty prompt" };

  // Trigger execution
  // Method 1: via app.queuePrompt (if available)
  if (typeof app.queuePrompt === "function") {
    const res = await app.queuePrompt(0); // 0 = insert at end of queue
    return { ok: true, data: res };
  }

  // Method 2: via api.queuePrompt
  const api = app.api;
  if (api && typeof api.queuePrompt === "function") {
    const res = await api.queuePrompt(0, promptData);
    return { ok: true, data: res };
  }

  // Method 3: direct HTTP fallback
  const resp = await fetch("/prompt", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: promptData.output,
      extra_data: { extra_pnginfo: { workflow: promptData.workflow } },
    }),
  });
  return { ok: resp.ok, data: await resp.json() };
}

Rendering

<!-- In toolbar, next to ⚙ settings button -->
<button class="mjr-icon-btn mjr-mfv-run-btn" title="Queue Prompt (Run)">
  <i class="pi pi-play"></i>
</button>

Visual state:

• Idle → green pi-play icon
• Running → pi-spin pi-spinner icon + disabled
• Error → red flash 1s then back to idle

---

4. Integration in FloatingViewer

4.1 Modification of _buildToolbar()

Add 2 buttons to existing toolbar:

// After existing capture/download button:

// --- Separator ---
const sep2 = document.createElement("div");
sep2.className = "mjr-mfv-toolbar-sep";
bar.appendChild(sep2);

// --- Settings Button (opens/closes sidebar) ---
const settingsBtn = document.createElement("button");
settingsBtn.type = "button";
settingsBtn.className = "mjr-icon-btn mjr-mfv-settings-btn";
settingsBtn.title = "Node Parameters";
const settingsIcon = document.createElement("i");
settingsIcon.className = "pi pi-cog";          // ⚙ PrimeIcons icon
settingsBtn.appendChild(settingsIcon);
settingsBtn.addEventListener("click", () => this._sidebar?.toggle());
bar.appendChild(settingsBtn);

// --- Run Button ---
const runBtn = createRunButton();              // from sidebarRunButton.js
bar.appendChild(runBtn);

4.2 Modification of render()

render() {
  const el = this._el;
  el.appendChild(this._buildHeader());
  el.appendChild(this._buildToolbar());
  el.appendChild(this._contentEl);

  // NEW: sidebar, mounted once, hidden by default
  this._sidebar = new WorkflowSidebar({
    hostEl: el,
    onClose: () => this._updateSettingsBtnState(false),
  });
  el.appendChild(this._sidebar.el);

  return el;
}

4.3 Selection Hook in floatingViewerManager.js

// In open():
_bindNodeSelectionListener();

// In close():
_unbindNodeSelectionListener();

---

5. CSS — Added Classes

/* ── Sidebar container ── */
.mjr-ws-sidebar {
  position: absolute;
  top: 0;
  right: 0;
  width: 280px;
  height: 100%;
  background: var(--comfy-menu-bg, #1a1a1a);
  border-left: 1px solid var(--border-color, #333);
  overflow-y: auto;
  transform: translateX(100%);
  transition: transform 0.2s ease;
  z-index: 1;
}
.mjr-ws-sidebar.open {
  transform: translateX(0);
}

/* ── Node sections ── */
.mjr-ws-node { padding: 8px 12px; border-bottom: 1px solid var(--border-color, #333); }
.mjr-ws-node-header { display: flex; align-items: center; justify-content: space-between; }
.mjr-ws-node-title { font-weight: 600; font-size: 13px; color: var(--input-text, #ddd); }
.mjr-ws-node-body { display: flex; flex-direction: column; gap: 6px; padding-top: 6px; }

/* ── Widget rows ── */
.mjr-ws-widget-row { display: flex; align-items: center; gap: 8px; }
.mjr-ws-widget-label { flex: 0 0 90px; font-size: 12px; color: var(--descrip-text, #999); }
.mjr-ws-widget-input { flex: 1; }
.mjr-ws-widget-input input,
.mjr-ws-widget-input select,
.mjr-ws-widget-input textarea {
  width: 100%;
  background: var(--comfy-input-bg, #222);
  color: var(--input-text, #ddd);
  border: 1px solid var(--border-color, #444);
  border-radius: 4px;
  padding: 4px 6px;
  font-size: 12px;
}

/* ── Run button ── */
.mjr-mfv-run-btn i { color: #4caf50; }
.mjr-mfv-run-btn.running i { color: var(--descrip-text, #999); }
.mjr-mfv-run-btn.error i { color: #f44336; }

/* ── Settings button active state ── */
.mjr-mfv-settings-btn.active i { color: var(--p-primary-color, #4fc3f7); }

---

6. Events and Data Flow

┌─────────────┐     click ⚙      ┌───────────────────┐
│  Toolbar     │ ───────────────► │  WorkflowSidebar  │
│  settingsBtn │                  │  .toggle()        │
└─────────────┘                  └────────┬──────────┘
                                          │ show()
                                          ▼
                              ┌──────────────────────┐
                              │ getSelectedNodes()   │
                              │ (comfyApiBridge)     │
                              └──────────┬───────────┘
                                         │
                              ┌──────────▼───────────┐
                              │ NodeWidgetRenderer   │
                              │ for each node        │
                              │   → widgetAdapters   │
                              └──────────┬───────────┘
                                         │ user edits input
                                         ▼
                              ┌──────────────────────┐
                              │ writeWidgetValue()   │
                              │ widget.value = x     │
                              │ widget.callback(x)   │
                              │ canvas.setDirty()    │
                              └──────────────────────┘

┌─────────────┐    click ▶      ┌───────────────────┐
│  Toolbar     │ ──────────────►│ queueCurrentPrompt│
│  runBtn      │                │ app.graphToPrompt()│
│              │                │ POST /prompt       │
└─────────────┘                └───────────────────┘

---

7. What We Do NOT Do

---

8. Implementation Checklist

• [x] Create js/features/viewer/workflowSidebar/widgetAdapters.js
• [x] Create js/features/viewer/workflowSidebar/NodeWidgetRenderer.js
• [x] Create js/features/viewer/workflowSidebar/WorkflowSidebar.js
• [x] Create js/features/viewer/workflowSidebar/sidebarRunButton.js
• [x] Modify FloatingViewer.js — add ⚙ + ▶ buttons in _buildToolbar()
• [x] Modify FloatingViewer.js — instantiate WorkflowSidebar in render()
• [x] Modify floatingViewerManager.js — onNodeSelected / onSelectionChange hooks
• [x] Add CSS classes in theme-comfy.css
• [x] Tests: workflowSidebar.vitest.mjs (DOM/adapters), sidebarRunButton.vitest.mjs (mock fetch)

Status: ✅ Complete — All items implemented and tested.

---

9. Final MFV Toolbar Visual Summary

[ Mode ][ Pin ▾]│[ Live ][ Preview ][ NodeStream ]│[ GenInfo ][ PopOut ][ Download ]│[ ⚙ Settings ][ ▶ Run ]│[ ✕ ]
                                                                                      └── NEW ──┘

---

10. Sidebar Position Setting

Users can customize sidebar placement via Settings:

• Right (default) — sidebar slides in from right
• Left — sidebar slides in from left
• Bottom — sidebar slides up from bottom

The setting applies immediately without reload and persists across sessions.

Frontend: Imperative vs. Vue ownership

Last updated: April 10, 2026

Summary

The frontend uses Vue 3 + Pinia for all major UI surfaces. Certain runtime modules remain imperative by design because they orchestrate cross-cutting behavior that predates or spans multiple Vue component trees.

Imperative by design

These modules are intentionally kept outside Vue's reactivity model:

Provisionally imperative (may migrate later)

Fully Vue-owned

All surfaces under js/vue/components/ and js/vue/composables/ are fully Vue-owned:

• Grid, sidebar, feed, settings panels, context menus
• All Pinia stores under js/stores/

Decision criteria

A module should stay imperative when:

1. It manages a lifecycle spanning multiple Vue app mounts/unmounts
2. It bridges to external APIs not under our control (ComfyUI)
3. It requires low-level DOM/canvas control where Vue overhead is measurable
4. Its mutation patterns don't map cleanly to reactive state (e.g. streaming events, Web Workers)

Frontend Lifecycle Conventions

Last updated: April 10, 2026

Vue component lifecycle

• Vue apps are created via js/vue/createVueApp.js with Pinia store injection.
• Components use onMounted / onUnmounted for DOM setup/teardown.
• Event listeners added in onMounted must be removed in onUnmounted.
• Pinia stores are the single source of truth for UI state.

Imperative runtime lifecycle

• panelRuntime.js manages the top-level panel init/destroy cycle.
• Feature modules (viewer, DnD, grid) expose init() / destroy() or start() / stop().
• The bootstrap sequence is:
1. bootstrap.js initializes the app context
2. panelRuntime.js sets up the panel shell
3. Vue apps mount into panel slots
4. Feature runtimes activate via events or direct calls

Teardown rules

1. Every addEventListener must have a matching removeEventListener on destroy.
2. Every setInterval / setTimeout must be cleared on destroy.
3. Pinia store subscriptions are auto-cleaned when the Vue app unmounts.
4. Custom event buses (events.js) listeners must be unsubscribed explicitly.

Bridge conventions

• comfyApiBridge.js: wraps ComfyUI API calls. Never call ComfyUI API directly from Vue components.
• panelStateBridge.js: syncs Pinia panel store with legacy imperative consumers. Will be removed when all consumers migrate to Vue.
• New bridges should be avoided. Prefer Pinia stores or composables for new features.

Graph Map Guide

Last Updated: May 10, 2026

Overview

Graph Map is the workflow-aware navigation view inside the Majoor Floating Viewer.

It is designed for one fast job: keep the saved workflow readable while you inspect the asset that came out of it.

Graph Map combines three things in one place:

• a large workflow map with readable node labels
• a selected-node detail panel with copy/import actions
• a small asset preview that keeps the current media visible while the panel refreshes

[Graph Map overview]

Why It Exists

When a workflow gets large, the usual minimap is useful for shape but not for understanding.

Graph Map adds the missing context:

• real node labels instead of anonymous boxes
• subgraph names that stay human-readable instead of raw UUID or hash identifiers
• a direct bridge between the saved workflow and the asset currently shown in the viewer

This is especially useful for video workflows, larger prompt-routing graphs, and pipelines that rely on nested subgraphs.

How To Open It

1. Open an asset in the Majoor Floating Viewer.
2. Switch the viewer to Graph Map mode.
3. If you also open the Node Parameters sidebar, use the Graph Map tab to keep the small preview and node details visible together.

Graph Map only appears when the selected asset contains readable workflow data.

What You See

1. Workflow overview

The large map shows the saved workflow structure with node labels, links, and the current selection highlight.

• loader, sampler, and output nodes remain easy to spot
• subgraphs are labeled with their real names when that metadata is available
• the selected node is outlined so you can keep your position while panning or zooming

2. Selected node detail panel

When you click a node in Graph Map, the detail panel shows the node title, its type, and the most useful simple parameters.

Available actions include:

• Copy node
• Import node
• Import workflow
• Transfer params to selected canvas node

You can also click individual parameter rows to copy a single value.

[Graph Map node detail]

3. Asset preview

The small preview keeps the active asset visible while you browse the workflow.

For video assets, the preview is meant to stay stable while Graph Map live refreshes, so it does not constantly restart or flicker during normal sidebar updates.

Navigation And Interaction

Canvas controls

• Click a node to select it
• Mouse wheel to zoom in or out
• Click-drag to pan around the map

Node detail workflow

• select the node that generated or refined the output you care about
• inspect the visible parameters
• copy a single value or the full node JSON
• import the node or the whole workflow back into the current canvas when needed

Subgraph Labels

Graph Map now prefers readable subgraph names over opaque identifiers.

In practice that means:

• named subgraphs are shown with their visible workflow name
• raw UUID or long hash node types are no longer the main label when a better name exists
• the same readable naming is reused in the map and the node detail panel

This matters most in larger reusable workflow blocks such as detailers, post-process passes, regional prompt groups, or custom routed subgraphs.

Best Use Cases

• understand which block produced the current result
• jump quickly between sampler, prompt, and save/output nodes
• inspect a subgraph without opening the full ComfyUI canvas layout
• compare outputs while keeping the originating node parameters close by
• reuse values from a saved asset back into the current canvas node

Limitations

• Graph Map depends on workflow metadata being present in the asset.
• If an asset has no embedded workflow, the panel cannot reconstruct the graph.
• The detail panel intentionally focuses on simple, copyable values; not every complex widget or linked input is shown as a plain field.

Related Docs

• VIEWER_FEATURE_TUTORIAL.md
• FLOATING_VIEWER_WORKFLOW_SIDEBAR.md
• HOTKEYS_SHORTCUTS.md

Majoor Assets Manager - Grid Optimization Checklist

Objectif: rendre le panel grid stable, previsible et rapide, surtout pendant la pagination, les updates backend, les changements de scope et la selection.

1. Stabiliser le contrat de chargement

Etat: fait pour le contrat critique.

• [x] appendNextPage ne doit pas vider la grille pendant la pagination.
• [x] La pagination adaptative doit continuer a charger quand une page recue ajoute 0 carte visible a cause du dedupe/filtrage.
• [x] Les updates backend ne doivent pas forcer un reload si la grille affiche deja des cartes visibles.
• [x] Separer explicitement les chemins reload, appendNextPage, refreshHead, upsertRealtime.
• [x] Garantir par tests que appendNextPage ne remplace pas toute la grille.
• [x] Garantir que appendNextPage ne touche jamais au scroll.
• [x] Garantir que appendNextPage ne purge jamais la selection.
• [x] Documenter les invariants de chargement dans le code.

2. Unifier l'etat grid

Etat: fait pour les nouveaux chemins, legacy garde en compatibilite.

• [x] Definir une source canonique lisible pour assets.
• [x] Definir une source canonique lisible pour pagination.
• [x] Definir une source canonique lisible pour selection.
• [x] Definir une source canonique lisible pour viewport.
• [x] Definir une source canonique lisible pour context.
• [x] Reduire completement le role des dataset DOM a une couche de compatibilite legacy.
• [x] Encapsuler les methodes _mjr* du container derriere une API unique (_mjrGridApi).
• [x] Ajouter des tests qui verifient l'etat canonique expose par le loader.

3. Proteger scroll et selection

Etat: fait pour pagination et reload partiel.

• [x] Eviter les reloads automatiques qui cassent scroll/selection quand la grille a deja des cartes visibles.
• [x] Sauver/restaurer un anchor visuel, pas seulement scrollTop.
• [x] Ne jamais appeler scrollToSelection apres pagination normale.
• [x] Garder la selection meme si l'asset selectionne n'est pas encore charge dans la page courante.
• [x] Distinguer "asset pas encore charge" de "resultat complet": prune seulement quand le resultat est complet.
• [x] Ajouter tests scroll + selection apres append.

4. Remplacer les reloads automatiques par des upserts

Etat: fait pour les chemins critiques.

• [x] Bloquer le reload automatique sur update index quand des cartes sont visibles.
• [x] Upsert en tete pour nouveaux assets compatibles avec le contexte courant.
• [x] Patch cible pour metadata existante.
• [x] Remove cible pour suppression.
• [x] Reload complet uniquement pour scope, filtre, tri, recherche ou collection.
• [x] Ajouter une API de decisions reload/appendNextPage/refreshHead/upsertRealtime.

5. Rendre la pagination plus previsible

Etat: fait pour les metriques de base.

• [x] Continuer avec une taille de page plus grande si une page ajoute 0 carte visible.
• [x] Mesurer pages demandees.
• [x] Mesurer assets recus.
• [x] Mesurer assets visibles ajoutes.
• [x] Mesurer assets masques/dedupliques.
• [x] Mesurer temps API.
• [x] Mesurer temps render.
• [x] Ajuster la taille de page selon le "visible yield" minimal: page vide visible => page suivante plus large.

6. Durcir la virtual grid

Etat: partiel.

• [x] Stabiliser les hauteurs de lignes via estimation unique par largeur/details.
• [x] Limiter les appels a measure() par coalescing requestAnimationFrame.
• [x] Adapter l'overscan selon vitesse de scroll.
• [x] Garder l'infinite scroll base sur distance au bas + prefetch controle.
• [x] Verifier que le sentinel ne declenche pas de reload: le chemin Vue utilise loadNextPage.

7. Ameliorer le cache snapshot

Etat: partiel, cache disque borne et memoire etendue.

• [x] Garder un cache disque borne pour eviter les gros JSON.stringify.
• [x] Garder un cache memoire complet des assets charges par contexte.
• [x] Snapshot par contexte exact: scope, sort, filtres, query, root, subfolder.
• [x] Hydratation instantanee puis refresh silencieux sans flash via preserveVisibleUntilReady.
• [x] Interdire le remplacement brutal de la grille apres hydratation snapshot.

8. Ajouter observabilite dev

Etat: fait pour le snapshot debug programmatique.

• [x] Ajouter un snapshot debug grid programmatique.
• [x] Exposer offset, total, loaded, visible.
• [x] Exposer selected, active, loading, done.
• [x] Exposer le dernier reload reason.
• [x] Exposer le dernier append reason.
• [x] Compter les resets.
• [x] Compter les restaurations de scroll.

9. Reduire la dependance au DOM legacy

Etat: fait pour les nouveaux chemins grid.

• [x] Faire du DOM une sortie d'affichage, pas une source d'etat.
• [x] Regrouper les API legacy _mjr* derriere _mjrGridApi pour les nouveaux appels.
• [x] Deplacer les lectures directes du DOM vers des selectors/bridges testes.
• [x] Supprimer progressivement les chemins dupliques Vue/legacy.

10. Renforcer les tests de stabilite

Etat: fait pour la stabilite critique.

• [x] Test: pagination adaptative quand plusieurs pages ajoutent 0 carte visible.
• [x] Test: pas de reload sur update backend quand la grille a deja des cartes visibles.
• [x] Test: selection state restore.
• [x] Test: pagination sans perte de scroll.
• [x] Test: reload avec anchor restore.
• [x] Test: selection persistante apres append.
• [x] Test: hidden/duplicate assets qui forcent adaptive paging.
• [x] Test: seul un scope/filter/sort/search/collection switch peut reset.
• [x] Test: snapshot hydrate puis refresh sans flash.

Regle directrice

• [x] Faire evoluer le grid vers: append/patch first, reload last.

Grid Refactor Roadmap

Current Problem

The current asset grid mixes too many responsibilities across a few large modules:

• VirtualAssetGridHost.vue handles virtualization, selection, stacks, duplicates, drag/drop, stats, skeletons, resize, keyboard behavior, and DOM bridge compatibility.
• useGridLoader.js handles pagination, localStorage snapshots, reloads, context detection, search, selection preservation, and realtime upserts.
• useVirtualGrid.js mixes scroll root detection, sentinel setup, IntersectionObserver, manual scroll fallback, page fetching, dedupe, and realtime insertion.

The target architecture is a single clear pipeline:

GridQuery
   |
   v
PagedAssetStore
   |
   v
VirtualRows
   |
   v
AssetCard

The grid should have one authority for query state, one authority for paged loading, and one authority for virtual rendering.

Target Module Layout

js/vue/grid/
  useGridQuery.js          // Reads and normalizes filters, scope, sort, search
  usePagedAssets.js        // Fetch, reset, append, cursor/offset state
  useInfiniteTrigger.js    // Observes the bottom sentinel and calls loadMore
  useGridVirtualRows.js    // TanStack virtual rows only
  useAssetCollection.js    // Dedupe, upsert, remove, item indexes
  useGridSnapshotCache.js  // Optional cache/hydrate layer, separate from loading

Progress Tracker

• [x] Phase 0 started: pagination freeze regression coverage added for consumed pages that add no visible cards.
• [x] Phase 0 started: infinite loading now has a sentinel trigger so pagination does not depend only on scroll events.
• [x] Phase 0 advanced: usePagedAssets now has synthetic 8000 asset pagination coverage.
• [x] Phase 1 complete for loader/page fetch: useGridQuery.js added with immutable query helpers and tests.
• [x] Phase 1 complete for loader/page fetch: snapshot keys, early-fetch keys, default browse detection, and page URL filters now use the shared query normalizer.
• [x] Phase 2 started: useAssetCollection.js added with Map-backed append/upsert/remove helpers and tests.
• [x] Phase 3 started: usePagedAssets.js added with a small offset state machine and tests.
• [x] Phase 2 advanced: legacy removal path now rebuilds assetIdSet / seenKeys through useAssetCollection helpers.
• [x] Phase 2 advanced: realtime upsert dedupe now rebuilds legacy indexes through useAssetCollection helpers.
• [x] Phase 3 advanced: legacy page-advance helper now delegates to usePagedAssets.resolvePageAdvance.
• [x] Phase 3 advanced: cursor state is supported by usePagedAssets and the legacy loader.
• [x] Phase 3 advanced: adaptive empty-page pagination now runs through usePagedAssets.loadPagesUntilVisible instead of living directly in useGridLoader.
• [x] Phase 3 advanced: useGridLoader syncs pagination through usePagedAssets.getPageState / setPageState instead of mutating the composable state fields directly.
• [x] Phase 3 advanced: pagination fetch/metrics wrapping is configured on usePagedAssets; loadNextPage now delegates visible-page loading through pagedAssets.loadUntilVisible.
• [x] Phase 3 complete for current loader: active offset / cursor / total / done writes are centralized through the usePagedAssets bridge.
• [x] Phase 4 started: useInfiniteTrigger.js added with a sentinel-based trigger and tests.
• [x] Phase 5 started: useGridVirtualRows.js added with row slicing helpers and tests.
• [x] Phase 5 started: VirtualAssetGridHost.vue now uses shared row slicing helpers.
• [x] Phase 7 started: useGridSnapshotCache.js extracted and useGridLoader.js now uses the cache API.
• [x] Phase 4 complete for production component: VirtualAssetGridHost.vue uses useInfiniteTrigger; scroll listener now only tracks velocity.
• [x] Phase 5 complete for production component: TanStack virtualizer ownership moved into useGridVirtualRows.js.
• [x] Phase 0 complete: add broad 8000+ asset scroll coverage.
• [x] Phase 1 complete: remaining panel/controller query dataset writes are moved behind a single bridge.
• [x] Phase 2 complete: asset dedupe/upsert/remove ownership moved to useAssetCollection.js.
• [x] Phase 3 complete: page loading ownership moved to usePagedAssets.js.
• [x] Phase 4 complete: only one infinite-load trigger remains in production grid flow.
• [x] Phase 5 complete: TanStack virtualization itself is owned by useGridVirtualRows.js.
• [x] Phase 6 complete: VirtualAssetGridHost.vue is mostly composition and rendering.
• [x] Phase 7 complete for current behavior: snapshot cache isolated behind useGridSnapshotCache.js.
• [x] Phase 8 complete: output browse backend cursor pagination is available with offset fallback.

The main component should eventually become composition and rendering only:

const query = useGridQuery();
const assets = usePagedAssets(query);
const virtualRows = useGridVirtualRows(assets.items);

useInfiniteTrigger({
    canLoad: assets.canLoadMore,
    loadMore: assets.loadMore,
});

Phase 0: Stabilize Before Refactor

Before moving code, keep the current pagination/virtual-scroll fixes and add non-regression coverage.

Recommended tests:

• 8000+ assets can scroll through multiple pages.
• A consumed backend page that adds zero visible cards does not freeze pagination.
• Scope/sort/filter changes during an in-flight request do not corrupt the grid.
• The debug snapshot exposes query, offset, total, done, loading, items.length, visible rows, and last load reason.

Phase 1: Create useGridQuery.js

Goal: stop reading gridContainer.dataset throughout pagination and fetch code.

Responsibilities:

• Read scope, sort, filters, search, collection, custom root, and grouping state.
• Normalize values.
• Produce an immutable query object.
• Produce a stable queryKey.

Target API:

const query = useGridQuery({
    gridContainerRef,
    panelStore,
});

Example immutable query:

export function createGridQuery({
    scope = "output",
    q = "*",
    subfolder = "",
    customRootId = "",
    kind = "",
    minRating = 0,
    workflowOnly = false,
    sort = "mtime_desc",
    groupStacks = false,
} = {}) {
    return Object.freeze({
        scope,
        q: String(q || "*").trim() || "*",
        subfolder,
        customRootId,
        kind,
        minRating,
        workflowOnly,
        sort,
        groupStacks,
    });
}

During migration, useGridQuery may still read DOM dataset values. That DOM dependency should live only in this module.

Phase 2: Create useAssetCollection.js

Goal: move dedupe, upsert, and remove behavior out of the loader and component.

Responsibilities:

• Own items.
• Maintain byId and byKey indexes.
• Append pages.
• Upsert realtime assets.
• Remove assets.
• Reset state.
• Gradually absorb duplicate/stack representative logic.

Target API:

const collection = useAssetCollection({
    assetKey,
    sortKey,
    groupStacks,
});

Example internal model:

const items = shallowRef([]);
const byId = new Map();
const byKey = new Map();

function assetKey(asset) {
    return [
        asset.source || asset.type || "output",
        asset.root_id || "",
        asset.subfolder || "",
        asset.filename || asset.filepath || "",
    ].join("|").toLowerCase();
}

function appendAssets(newAssets) {
    const next = items.value.slice();

    for (const asset of newAssets || []) {
        const id = String(asset.id || "");
        const key = assetKey(asset);

        if (id && byId.has(id)) continue;
        if (key && byKey.has(key)) continue;

        next.push(asset);
        if (id) byId.set(id, asset);
        if (key) byKey.set(key, asset);
    }

    items.value = next;
}

function upsertAsset(asset) {
    const id = String(asset.id || "");
    const key = assetKey(asset);
    const existing = (id && byId.get(id)) || (key && byKey.get(key));

    if (existing) {
        Object.assign(existing, asset);
        items.value = items.value.slice();
        return;
    }

    appendAssets([asset]);
}

Keep legacy AssetCardRenderer.appendAssets as a temporary adapter until Vue state is the sole source of truth.

Phase 3: Create usePagedAssets.js

Goal: replace useGridLoader.js with a smaller state machine.

Minimal state:

const state = reactive({
    items: [],
    offset: 0,
    total: null,
    loading: false,
    error: null,
    done: false,
    requestId: 0,
});

Target API:

const assets = usePagedAssets({
    query,
    collection,
    pageSize,
    fetchPage,
});

Core behavior:

async function reset(nextQuery) {
    state.requestId += 1;
    collection.reset();
    state.offset = 0;
    state.total = null;
    state.done = false;
    state.error = null;
    query.value = nextQuery;

    await loadMore();
}

async function loadMore() {
    if (state.loading || state.done) return;

    const requestId = state.requestId;
    state.loading = true;

    try {
        const page = await fetchAssetsPage({
            query: query.value,
            offset: state.offset,
            limit: pageSize.value,
        });

        if (requestId !== state.requestId) return;
        appendPage(page);
    } catch (err) {
        if (requestId !== state.requestId) return;
        state.error = err;
    } finally {
        if (requestId === state.requestId) {
            state.loading = false;
        }
    }
}

function appendPage(page) {
    const assets = Array.isArray(page.assets) ? page.assets : [];

    collection.append(assets);
    state.offset += assets.length;

    if (page.total != null) {
        state.total = page.total;
    }

    if (!assets.length) {
        state.done = true;
    }

    if (state.total != null && state.offset >= state.total) {
        state.done = true;
    }
}

Keep resolvePageAdvanceCount() while the backend uses offset pagination and can return pages that are consumed but mostly hidden or deduped.

Phase 4: Create useInfiniteTrigger.js

Goal: keep one mechanism for deciding when to load more.

Prefer a single sentinel-based IntersectionObserver.

export function useInfiniteTrigger({
    rootRef,
    enabled,
    canLoad,
    loadMore,
    rootMargin = "900px",
}) {
    let observer = null;
    const sentinelRef = ref(null);

    onMounted(() => {
        observer = new IntersectionObserver(
            async ([entry]) => {
                if (!entry?.isIntersecting) return;
                if (!enabled.value || !canLoad.value) return;
                await loadMore();
            },
            {
                root: rootRef.value,
                rootMargin,
                threshold: 0.01,
            },
        );

        if (sentinelRef.value) observer.observe(sentinelRef.value);
    });

    onBeforeUnmount(() => {
        observer?.disconnect();
        observer = null;
    });

    return { sentinelRef };
}

Remove progressively:

• manual scroll listener fallback;
• dynamic scroll root detection from pagination code;
• userScrolled;
• allowUntilFilled;
• ignoreNextScroll;
• sentinel ownership from useVirtualGrid.js.

Phase 5: Create useGridVirtualRows.js

Goal: isolate TanStack virtualization.

export function useGridVirtualRows({
    scrollRef,
    items,
    columnCount,
    estimateRowHeight,
}) {
    const rowCount = computed(() =>
        Math.ceil(items.value.length / columnCount.value),
    );

    const virtualizer = useVirtualizer(
        computed(() => ({
            count: rowCount.value,
            getScrollElement: () => scrollRef.value,
            estimateSize: () => estimateRowHeight.value,
            overscan: 8,
        })),
    );

    const virtualRows = computed(() =>
        virtualizer.value.getVirtualItems().map((row) => {
            const start = row.index * columnCount.value;
            return {
                virtual: row,
                items: items.value.slice(start, start + columnCount.value),
            };
        }),
    );

    return {
        virtualizer,
        virtualRows,
        totalSize: computed(() => virtualizer.value.getTotalSize()),
    };
}

VirtualAssetGridHost.vue should no longer compute virtual rows directly once this exists.

Phase 6: Reduce VirtualAssetGridHost.vue

Target responsibilities:

• Compose the grid composables.
• Render rows and cards.
• Expose temporary legacy APIs.

Move out:

• page loading;
• dedupe and upsert;
• snapshot/cache logic;
• stack/duplicate collection bookkeeping;
• infinite-scroll decision logic;
• query parsing;
• DOM dataset reads except for transitional bridge code.

The DOM bridge should remain only as compatibility for older imperative callers.

Phase 7: Extract Snapshot Cache

Goal: localStorage cache becomes an optional hydration layer, not part of pagination.

Create:

js/vue/grid/useGridSnapshotCache.js

Responsibilities:

• Load snapshot by queryKey.
• Save snapshot debounced.
• Enforce TTL.
• Enforce storage size limits.
• Never fetch network pages.

Target flow:

const snapshot = useGridSnapshotCache(query);

assets.hydrate(snapshot.items);
assets.refresh();

The network store remains the source of truth.

Phase 8: Add Cursor Pagination Backend

Long-term performance target: replace deep offset paging.

Current:

/mjr/am/list?limit=80&offset=8000

Target:

/mjr/am/list?limit=80&cursor=mtime:1730000000,id:4567

Response:

{
  "assets": [],
  "next_cursor": "mtime:1730000000,id:4567",
  "has_more": true
}

Frontend state becomes:

const state = reactive({
    items: [],
    cursor: null,
    hasMore: true,
    loading: false,
});

Cursor migration plan:

1. Keep offset pagination compatible.
2. Add optional cursor parameter.
3. For mtime_desc, cursor is based on (mtime, id).
4. For name_asc and name_desc, cursor is based on (filename, id).
5. Frontend uses cursor when the backend provides next_cursor, otherwise falls back to offset.

Recommended Execution Order

1. Add tests and debug state for the current behavior.
2. Create useGridQuery.js.
3. Create useAssetCollection.js.
4. Create usePagedAssets.js.
5. Create useInfiniteTrigger.js.
6. Create useGridVirtualRows.js.
7. Reduce VirtualAssetGridHost.vue.
8. Extract useGridSnapshotCache.js.
9. Add backend cursor pagination.

Do not start with backend cursor pagination. First make the frontend have a single loading authority. Then offset-to-cursor becomes a much smaller change.

Majoor Assets Manager - Hotkeys & Keyboard Shortcuts Guide

Version: 2.4.5 Last Updated: May 11, 2026

Overview

This guide covers all active keyboard shortcuts for the Majoor Assets Manager, including the new Majoor Floating Viewer (MFV).

---

Table of Contents

• Global / Panel Hotkeys
• Grid View Hotkeys
• Standard Viewer Hotkeys
• Majoor Floating Viewer (MFV) Hotkeys
• Video Playback Hotkeys
• Mouse Shortcuts

---

Global / Panel Hotkeys

These shortcuts work globally in the Assets Manager panel.

---

Grid View Hotkeys

These shortcuts apply when the asset grid has focus.

Navigation & Selection

Organization & Rating

File Operations

---

Standard Viewer Hotkeys

These shortcuts apply when the Standard Viewer overlay is open (double-click on asset).

General

Navigation

Tools & Analysis

Enhancement Tools

Analysis Overlays

---

Majoor Floating Viewer (MFV) Hotkeys

These shortcuts apply when the Majoor Floating Viewer panel is open.

General Controls

Panel And Media Interaction

Node Stream follows the currently selected compatible node when enabled. Grid compare and Graph Map are available from the MFV toolbar or mode menu rather than dedicated keyboard shortcuts.

Video Controls (MFV)

Click once on the inline player surface to give it focus before using the playback shortcuts above.

---

Video Playback Hotkeys

These shortcuts apply when playing video content in the viewer.

Playback Control

Frame Navigation

In/Out Points (Edit Marks)

Speed Control

Audio

Video audio is automatically unmuted after first user interaction (play, seek, or frame step).

---

Mouse Shortcuts

Grid View

Viewer

Floating Viewer

---

Quick Reference Card

Most Used Shortcuts

Grid Navigation:  Arrow keys
Open Viewer:      Enter / Double-click
Rate:             0-5 keys
Search:           Ctrl+F / Ctrl+K
Scan:             Ctrl+S
Tags:             T
Collection:       B
Close Viewer:     Esc
Zoom:             Mouse wheel
Pan:              Click+drag

Viewer Essentials

Fullscreen:       F
Info Panel:       D
Pixel Probe:      I
Loupe:            L
Zebra:            Z
Grid:             G
1:1 Zoom:         Alt+1

MFV Essentials

Toggle MFV:       V
Compare Mode:     C
Live Stream:      L
KSampler Preview: K
Node Stream:      N
Play/Pause:       Space

---

Customization

Remapping Shortcuts

Currently, shortcuts are hardcoded. Future versions may support customization via:

• Browser extensions
• ComfyUI keymap settings
• Configuration file

Conflicts with ComfyUI

The following shortcuts may conflict with ComfyUI globals:

• Ctrl+S: Also triggers ComfyUI workflow save
• Delete: Also deletes ComfyUI nodes
• Ctrl+Z: ComfyUI undo (not overridden)

When the Assets Manager panel has focus, its shortcuts take precedence.

---

Accessibility

Keyboard-Only Navigation

All features are accessible via keyboard:

• Tab through UI elements
• Enter/Space to activate
• Arrow keys to navigate
• Esc to close dialogs

Screen Reader Support

• ARIA labels on interactive elements
• Status announcements for operations
• Alt text on thumbnails

---

_Hotkeys & Shortcuts Guide Version: 2.4.5_ _Last Updated: May 11, 2026_ _Compatible with Majoor Assets Manager v2.4.4+_

Majoor Assets Manager - Installation Guide

Version: 2.4.5 Last Updated: April 7, 2026

Overview

This guide provides detailed instructions for installing and configuring the Majoor Assets Manager for ComfyUI. Follow these steps to get the extension up and running with all its features.

Recent highlights: Improved metadata parsing, expanded floating viewer compare modes, better workflow grouping with job and stack IDs, and support for a configurable Index DB directory (useful on network drives or NAS storage).

Prerequisites

System Requirements

• ComfyUI installation (≥ 0.13.0 recommended)
• Python 3.10, 3.11, or 3.12 (3.13 compatible)
• At least 500MB free disk space for the extension and dependencies
• Administrator privileges (for installation and optional tool installations)

Supported Platforms

• Windows: 10/11
• macOS: 10.15 or higher
• Linux: Ubuntu 22.04+, Debian 12+, Fedora, or equivalent

Quick Installation (Recommended)

Using ComfyUI Manager

1. Open ComfyUI Manager in your browser
2. Find "Majoor Assets Manager" in the extensions list
3. Click "Install" next to the extension
4. Wait for the installation to complete
5. Restart ComfyUI completely
6. The extension should now be available in the Assets Manager tab

Manual Installation

Step 1: Clone the Repository

Open your terminal/command prompt and navigate to your ComfyUI custom_nodes directory:

cd /path/to/your/ComfyUI/custom_nodes

Clone the repository:

git clone https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager ComfyUI-Majoor-AssetsManager

Step 2: Install Python Dependencies

Navigate to the extension directory and install the required packages:

cd ComfyUI-Majoor-AssetsManager
pip install -r requirements.txt

If you want the optional AI/vector features as well, install the extra vector stack too:

pip install -r requirements.txt -r requirements-vector.txt

If you are contributing to the project itself, install the local dev/test tooling separately:

pip install -r requirements-dev.txt

Dependency ownership and update rules are documented in docs/DEPENDENCY_POLICY.md.

Faster installs with uv: If you have uv installed, you can use it as a drop-in replacement for significantly faster dependency resolution:

```bash

uv pip install -r requirements.txt

```

Install uv with pip install uv or see the uv documentation for other methods.

For AI/vector features with uv:

```bash

uv pip install -r requirements.txt -r requirements-vector.txt

```

For contributor tooling with uv:

```bash

uv pip install -r requirements-dev.txt

```

Step 3: Restart ComfyUI

Stop your ComfyUI server completely and restart it to load the new extension.

Optional Dependencies (Highly Recommended)

For full functionality including metadata extraction and file tagging, install these external tools:

Windows Installation

Option A: Using Scoop Package Manager

1. Install Scoop if you don't have it:

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   irm get.scoop.sh | iex

1. Install the required tools:

   scoop install ffmpeg exiftool

Option B: Using Chocolatey Package Manager

1. Install Chocolatey if you don't have it:

   Set-ExecutionPolicy Bypass -Scope Process -Force
   [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
   iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

1. Install the required tools:

   choco install -y ffmpeg exiftool

Option C: Using WinGet

winget install -e --id Gyan.FFmpeg
winget install -e --id OliverBetz.ExifTool

Option D: Manual Installation

1. FFmpeg: Download from https://www.gyan.dev/ffmpeg/builds/
• Extract to a folder (e.g., C:\ffmpeg)
• Add C:\ffmpeg\bin to your system PATH

1. ExifTool: Download from https://exiftool.org/
• Download exiftool-#.##.zip
• Extract to a folder (e.g., C:\exiftool)
• Add C:\exiftool to your system PATH

macOS Installation

Using Homebrew (Recommended)

1. Install Homebrew if you don't have it:

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1. Install the required tools:

   brew install ffmpeg exiftool

Linux Installation

Ubuntu/Debian

sudo apt update
sudo apt install -y ffmpeg libimage-exiftool-perl

Fedora/RHEL

sudo dnf install -y ffmpeg perl-Image-ExifTool

Arch Linux

sudo pacman -S ffmpeg exiftool

Verification Steps

After installation, verify everything is working:

Step 1: Check Extension Loading

1. Start ComfyUI
2. Look for the Assets Manager tab in the interface
3. Check the console/logs for any error messages during startup

Step 2: Verify External Tools (if installed)

Open a terminal/command prompt and run:

exiftool -ver
ffprobe -version

Both commands should return version information without errors.

Step 3: Test Basic Functionality

1. Open the Assets Manager in ComfyUI
2. Switch between different scopes (Outputs, Inputs, Custom, Collections)
3. Perform a simple search to verify indexing is working
4. Try opening the viewer for an asset

Configuration

Environment Variables

You can configure the extension using environment variables. Add these to your shell profile or set them before starting ComfyUI:

# Override default output directory
export MAJOOR_OUTPUT_DIRECTORY="/path/to/your/output"

# Override index database directory (useful on NAS/SMB/network drives)
# By default the index lives at <output>/_mjr_index/
# Move it to a local disk if your output is on a slow or SMB-mounted drive:
export MJR_AM_INDEX_DIRECTORY="/var/local/mjr_index"

# Specify tool paths if not in system PATH
export MAJOOR_EXIFTOOL_PATH="/path/to/exiftool"
export MAJOOR_FFPROBE_PATH="/path/to/ffprobe"

# Set media probe backend (auto, exiftool, ffprobe, both)
export MAJOOR_MEDIA_PROBE_BACKEND="auto"

UI Output Directory Override

If you prefer not to change shell startup scripts, you can override the generation output folder directly from the ComfyUI settings UI:

1. Open Settings → Majoor Assets Manager → Advanced and search for path if needed.
2. Edit Generation Output Directory.
3. Save the new directory path. Leave the field empty to fall back to the current backend default.

[Output directory override in Majoor settings]

Windows Batch File Example

Create a batch file to set environment variables and start ComfyUI:

@echo off
set MAJOOR_MEDIA_PROBE_BACKEND=auto
REM Optional: move the index DB to a local SSD if output is on a network drive
set MJR_AM_INDEX_DIRECTORY=C:\mjr_index

REM Start ComfyUI with the environment variables
cd /d "C:\path\to\ComfyUI"
python main.py --auto-launch
pause

Remote Access Write Permissions

If you open ComfyUI from another machine, Majoor blocks write operations by default unless you explicitly allow them.

Recommended setup: define MAJOOR_API_TOKEN on the machine that runs ComfyUI, then send the same token from the remote client.

If no persistent token has been configured yet, Majoor can also bootstrap the first remote session token automatically for a signed-in ComfyUI user over HTTPS. Local loopback browser sessions can also recover a write session automatically after restart/new tab without a separate ComfyUI sign-in step.

Older installs that only kept a legacy token hash are recovered automatically on the first successful bootstrap: Majoor rotates to a fresh persistent token and re-authorizes the current browser session.

Recent builds also expose the main remote security toggles directly in Majoor Settings, so a signed-in ComfyUI user can usually complete the initial setup without editing shell startup scripts manually:

• Require Token For All Writes
• Recommended Remote LAN Setup to auto-generate a token and apply the safest common LAN defaults in one click
• Allow HTTP Token Transport for trusted LAN-only HTTP setups
• Allow Remote Full Access if you explicitly want no-token remote writes
• API Token for the fixed shared token value

Fastest Settings-only path for a trusted LAN

1. Open Majoor Settings in ComfyUI.
2. Turn on Recommended Remote LAN Setup.
3. Confirm that the current browser session is authorized.
4. Keep Allow Remote Full Access off unless you explicitly want no-token remote writes.

That preset automatically:

• generates a strong API token if none exists yet
• enables Require Token For All Writes
• keeps Allow Remote Full Access disabled
• enables Allow HTTP Token Transport automatically when the current session is plain HTTP on a non-loopback LAN address
• injects the token into the current browser session immediately so write actions work without a manual copy/paste step

Visual confirmation inside Assets Manager:

• the runtime status widget now shows a Write auth: line such as Write auth: active ...ABCD
• if the browser session is missing authorization while the server still requires a token, the same widget reports that state directly

If you need to authorize a different browser or device, either:

• enter a fixed shared value in Security -> Majoor: API Token, or
• open that browser while signed in to ComfyUI and let Majoor bootstrap a session token there

Windows batch example

@echo off
set MAJOOR_API_TOKEN=change-this-to-a-long-random-secret

cd /d "C:\path\to\ComfyUI"
python main.py --listen 0.0.0.0 --port 8188
pause

Windows PowerShell example

$env:MAJOOR_API_TOKEN = "change-this-to-a-long-random-secret"
Set-Location "C:\path\to\ComfyUI"
python main.py --listen 0.0.0.0 --port 8188

Linux/macOS shell example

export MAJOOR_API_TOKEN="change-this-to-a-long-random-secret"
cd /path/to/ComfyUI
python main.py --listen 0.0.0.0 --port 8188

Unsafe fallback

If you really want to allow remote writes without a token, set MAJOOR_ALLOW_REMOTE_WRITE=1 before starting ComfyUI. This is less safe and should only be used on trusted networks.

export MAJOOR_ALLOW_REMOTE_WRITE=1
python main.py --listen 0.0.0.0 --port 8188

Remote client side

• In the ComfyUI UI, open the Majoor settings and set the same token under Security -> Majoor: API Token.
• For direct API calls, send either X-MJR-Token: <token> or Authorization: Bearer <token>.
• Restart ComfyUI after changing environment variables so the new values are picked up.
• On first remote use, if ComfyUI authentication is enabled and no persistent token exists yet, Majoor can provision the initial session token automatically.

Troubleshooting

Extension Not Appearing

• Verify the folder is named correctly: ComfyUI-Majoor-AssetsManager
• Check that all files were downloaded properly
• Ensure ComfyUI was restarted after installation
• Look for error messages in the ComfyUI console

Missing Dependencies Error

If you see messages about missing dependencies:

# Navigate to the extension directory
cd ComfyUI-Majoor-AssetsManager
pip install -r requirements.txt

If the error is related to AI/vector search features, install the optional vector stack too:

pip install -r requirements.txt -r requirements-vector.txt

External Tools Not Found

If metadata extraction isn't working:

1. Verify tools are installed: exiftool -ver and ffprobe -version
2. Check if tools are in your system PATH
3. Set environment variables to point to the executables directly

Permission Errors

• Ensure ComfyUI has read/write access to the output directory
• On Windows, run as administrator if needed
• On Unix systems, check file permissions with ls -la

Slow Performance

• The first scan may take time for large directories
• Subsequent scans will be faster due to incremental indexing
• Consider excluding very large directories that don't contain relevant assets

Post-Installation Setup

First-Time Usage

1. Open ComfyUI and navigate to the Assets Manager tab
2. The extension will automatically begin indexing your output directory
3. Wait for the initial scan to complete (progress shown in status bar)
4. Use the search bar to find assets
5. Right-click on assets to access context menus

Adding Custom Directories

1. Right-click in the Assets Manager interface
2. Select "Add Custom Root"
3. Enter the path to your custom directory
4. The directory will be added to the Custom scope

Creating Your First Collection

1. Select one or more assets
2. Right-click and choose "Add to Collection"
3. Create a new collection or add to an existing one
4. Access your collections from the Collections tab

Updates

Using ComfyUI Manager

Updates will be available through the ComfyUI Manager interface when released.

Manual Updates

cd ComfyUI/custom_nodes/ComfyUI-Majoor-AssetsManager
git pull origin main
pip install -r requirements.txt --upgrade

If you use AI/vector features, also upgrade the optional vector requirements:

pip install -r requirements.txt -r requirements-vector.txt --upgrade

Remember to restart ComfyUI after updating.

Uninstallation

Using ComfyUI Manager

Simply click "Uninstall" in the ComfyUI Manager interface.

Manual Removal

1. Delete the ComfyUI-Majoor-AssetsManager folder from custom_nodes
2. Restart ComfyUI
3. The extension will be completely removed

---

Installation Guide Version: 1.1 Last Updated: April 5, 2026

Majoor Floating Viewer (MFV) Guide

Last Updated: May 10, 2026

Overview

The Majoor Floating Viewer is the fast workflow cockpit inside Majoor Assets Manager.

It is built for one practical goal: keep you close to the current result while giving you the controls you need to compare, follow execution, inspect node outputs, adjust workflow parameters, and relaunch or stop a run without bouncing back and forth between panels.

This guide focuses only on MFV.

[MFV overview]

What MFV Covers

MFV is not just a floating preview anymore. It brings together:

• compare modes
• A/B/C/D pin slots
• format and guide overlays
• Live Stream
• Node Stream
• KSampler Preview
• Node Parameters
• Run and Stop actions
• pop-out / detached window workflow

Opening MFV

You can open the Majoor Floating Viewer from the Assets Manager panel or from the viewer-related UI that already targets MFV in your current setup.

Typical workflow:

1. Select an asset in the grid.
2. Open the Floating Viewer.
3. Pick the mode or stream you want from the MFV toolbar.

Compare Modes

MFV supports several ways to compare results depending on how much context you need on screen.

Simple mode

Use this when you want the cleanest single-asset view.

• one asset visible at a time
• best for inspection and overlay controls
• good default when you are reviewing video or a single final image

A/B compare

Use A/B compare when you want to flip between two candidates quickly.

• ideal for subtle sampler, CFG, or prompt changes
• good for before/after review
• especially useful when one slot is pinned and the other stays live

Side-by-side compare

Use side-by-side when both assets must remain visible at the same time.

• stronger spatial comparison than A/B switching
• useful for composition and crop review
• good when synchronized zoom/pan matters

Grid compare

Use grid compare when you want to review several references together.

• suited to broader sweeps
• pairs naturally with A/B/C/D pins
• good for sampler or prompt variation sets

[MFV compare and pins]

Pin Mode (A/B/C/D)

The pin system lets you lock up to four references so they stay stable while other slots keep changing.

What pins are for

• keep your best result as a baseline
• compare new generations against a fixed reference
• hold four selected results in grid compare

Practical pin patterns

• A pinned, B live: best pattern for iterative prompt or sampler work
• A/B pinned: useful for deliberate side-by-side review
• A/B/C/D pinned: useful for a final selection round in grid compare

Pinned slots are meant to remain stable while unpinned content can keep following the current workflow output.

Format And Guides

MFV can also act as a framing and presentation surface.

Format overlays

Use format controls when you want to preview how the media reads inside a target ratio or crop.

• useful for cinematic framing checks
• useful when comparing several outputs against the same intended presentation shape

Guides

Use guides when you want composition references directly in the viewer.

• rule-of-thirds style guidance
• safe-area style guidance
• fast visual help during compare sessions

These controls matter most when MFV is used as a review surface, not just as a passive preview.

Live Stream

Live Stream is for final outputs.

• follows newly completed outputs after execution
• best for monitoring what the workflow actually saves
• keeps MFV aligned with the most recent finished result

Use Live Stream when you care about the last completed output file, not the currently selected node.

Node Stream

Node Stream is for selected-node media.

• follows the node you click in ComfyUI when that node exposes frontend media
• useful for preview nodes, save nodes, loader nodes, and compatible live-preview surfaces
• good for debugging a specific point in the workflow

Use Node Stream when you want to inspect the media attached to the selected node, not the final workflow output.

KSampler Preview

KSampler Preview is for denoising-step frames during execution.

• shows the progression while the workflow is still running
• useful when you want feedback before the final file exists
• different from Live Stream and different from Node Stream

In short:

• Live Stream = final outputs
• Node Stream = selected node media
• KSampler Preview = execution preview frames

[MFV streams]

Node Parameters

Node Parameters let you inspect and edit the workflow node that produced the current result without leaving MFV.

Typical values you will use there:

• prompt text
• seed
• steps
• CFG
• sampler
• scheduler

This makes MFV practical for short iteration loops where you want to tweak one or two values and launch another run immediately.

Run And Stop

MFV is not only a viewer surface. It also exposes execution actions.

Run

Use Run when you want to queue the current workflow again directly from MFV.

Good use cases:

• prompt iteration
• seed changes
• sampler or scheduler changes
• quick compare loops with pinned references

Stop

Use Stop when you want to abort the current generation without leaving the viewer surface.

Good use cases:

• a bad direction is obvious early
• KSampler Preview already tells you the run is not worth finishing
• you want to reclaim time before launching the next variation

Pop-Out

Pop-out detaches MFV from the main ComfyUI window so it can live as a separate viewer window.

This is useful when:

• you want MFV on a second screen
• you want the canvas and the viewer visible side by side
• you want to keep MFV open as a dedicated monitoring surface while working on the graph elsewhere

[MFV controls and actions]

Graph Map As A Natural Companion

Graph Map is the workflow-context side of MFV.

Use MFV when you want to compare outputs, follow streams, inspect node parameters, or relaunch quickly. Open Graph Map when you want to understand where the current result came from in the saved workflow.

[Graph Map overview]

Graph Map complements MFV by adding:

• readable node and subgraph names instead of raw opaque identifiers
• a selected-node detail panel with copy-ready parameters and actions
• a workflow overview that stays close to the current asset preview

Typical pairing:

1. Review the latest result in MFV.
2. Open Graph Map to locate the relevant node or subgraph.
3. Inspect the selected node details.
4. Return to Node Parameters or Run inside MFV for the next iteration.

For the full Graph Map walkthrough, including the selected-node detail panel, see GRAPH_MAP.md.

Recommended Workflows

Fast prompt iteration

1. Pin your baseline in slot A.
2. Edit prompt or seed in Node Parameters.
3. Click Run.
4. Let the unpinned slot follow Live Stream.

Execution monitoring

1. Turn on KSampler Preview.
2. Watch denoising steps during the run.
3. Keep Live Stream ready for the final output.

Node-focused debugging

1. Turn on Node Stream.
2. Click the relevant node in ComfyUI.
3. Inspect available frontend media from that node.

Two-screen review

1. Pop out MFV.
2. Keep ComfyUI on the main screen.
3. Use the detached viewer as a dedicated compare and monitoring surface.

Related Docs

• GRAPH_MAP.md
• VIEWER_FEATURE_TUTORIAL.md
• FLOATING_VIEWER_WORKFLOW_SIDEBAR.md
• HOTKEYS_SHORTCUTS.md
• SETTINGS_CONFIGURATION.md

Plugin Development Quick Reference

Quick Start

1. Create Plugin File

# my_plugin.py
from mjr_am_backend.features.metadata.plugin_system.base import (
    MetadataExtractorPlugin,
    ExtractionResult,
)

class MyExtractor(MetadataExtractorPlugin):
    @property
    def name(self): return "my_extractor"

    @property
    def supported_extensions(self): return ['.png']

    @property
    def priority(self): return 50

    async def extract(self, filepath):
        data = {"key": "value"}
        return self._create_success_result(data)

2. Install Plugin

# Copy to plugin directory
cp my_plugin.py ~/.comfyui/majoor_plugins/extractors/

3. Reload Plugins

# Via API
curl -X POST http://localhost:8188/mjr/am/plugins/reload

# Or restart ComfyUI

---

Plugin API

Required Properties

Required Methods

Optional Properties

Optional Methods

Helper Methods

---

ExtractionResult

@dataclass
class ExtractionResult:
    success: bool           # True if extraction succeeded
    data: Dict[str, Any]    # Extracted metadata
    error: Optional[str]    # Error message if failed
    extractor_name: str     # Plugin name
    confidence: float       # 0.0-1.0 confidence score

Standard Metadata Fields

{
    # Standard ComfyUI metadata
    "prompt": str,              # Main prompt
    "negative_prompt": str,     # Negative prompt
    "seed": int,                # Random seed
    "steps": int,               # Sampling steps
    "sampler": str,             # Sampler name
    "cfg": float,               # CFG scale
    "models": list,             # Model names
    "loras": list,              # LoRA info

    # Custom data
    "custom_data": dict,        # Node-specific data
    "workflow": dict,           # Workflow JSON
    "file_info": dict,          # File information
}

---

Plugin Lifecycle

┌─────────────────────────────────────────────────────────────┐
│ 1. Discovery                                                 │
│    - Plugin file found in plugin directory                  │
│    - Validated by PluginValidator                           │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Loading                                                   │
│    - Module imported                                        │
│    - Extractor classes instantiated                          │
│    - Registered in PluginLoader                             │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Runtime                                                   │
│    - can_extract() called to check compatibility            │
│    - pre_extract() called for validation                    │
│    - extract() called for extraction                        │
│    - post_extract() called for enrichment                   │
└─────────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Cleanup                                                   │
│    - cleanup() called on unload                             │
│    - Resources released                                     │
└─────────────────────────────────────────────────────────────┘

---

Security

Blocked Patterns

The following patterns are blocked during validation:

# Code execution
eval()
exec()
compile()

# OS access
os.system()
os.popen()
subprocess.*

# Network access
socket.*
requests.*
urllib.*

# Unsafe deserialization
pickle.load()
marshal.load()

# Dynamic imports
__import__()
importlib.reload()

Allowed Imports

# Standard library (safe)
typing, collections, functools, itertools, pathlib
json, re, hashlib, base64, io, struct
logging, dataclasses, enum, abc, contextlib
asyncio, datetime, time, math

# Third-party (safe)
PIL (Pillow)
numpy

---

Testing

Unit Test Example

import pytest
from my_plugin import MyExtractor

@pytest.mark.asyncio
async def test_extraction(tmp_path):
    extractor = MyExtractor()

    # Create test file
    test_file = tmp_path / "test.png"
    test_file.write_bytes(b"fake png data")

    # Test extraction
    result = await extractor.extract(str(test_file))

    assert result.success is True
    assert "key" in result.data
    assert result.confidence > 0

Debug Logging

# Enable debug logging
export MJR_PLUGIN_LOG_LEVEL=DEBUG

# In plugin code
logger.debug(f"Debug message: {data}")
logger.info(f"Info message: {data}")
logger.warning(f"Warning message: {data}")
logger.error(f"Error message: {error}")

---

API Endpoints

Example Requests

# List plugins
curl http://localhost:8188/mjr/am/plugins/list

# Enable plugin
curl -X POST http://localhost:8188/mjr/am/plugins/my_extractor/enable

# Disable plugin
curl -X POST http://localhost:8188/mjr/am/plugins/my_extractor/disable

# Reload plugins
curl -X POST http://localhost:8188/mjr/am/plugins/reload

---

Troubleshooting

Plugin Not Loading

Extraction Fails

Performance Issues

---

Best Practices

Code Organization

# Good: Organized extraction logic
class MyExtractor(MetadataExtractorPlugin):
    async def extract(self, filepath):
        if filepath.endswith('.png'):
            return await self._extract_png(filepath)
        elif filepath.endswith('.json'):
            return await self._extract_json(filepath)
        return self._create_error_result("Unsupported format")

    async def _extract_png(self, filepath):
        # PNG-specific logic
        pass

    async def _extract_json(self, filepath):
        # JSON-specific logic
        pass

Error Handling

# Good: Comprehensive error handling
async def extract(self, filepath):
    try:
        # Pre-checks
        if not Path(filepath).exists():
            return self._create_error_result("File not found")

        # Extraction
        data = await self._do_extract(filepath)
        return self._create_success_result(data)

    except FileNotFoundError as e:
        return self._create_error_result(f"File not found: {e}")
    except PermissionError as e:
        return self._create_error_result(f"Permission denied: {e}")
    except Exception as e:
        logger.exception(f"Extraction failed")
        return self._create_error_result(str(e))

Logging

# Good: Appropriate logging levels
logger.debug(f"Processing file: {filepath}")      # Debug info
logger.info(f"Extracted metadata from {filepath}") # Success
logger.warning(f"Missing field: {field}")          # Non-critical issue
logger.error(f"Extraction failed: {error}")        # Critical error

---

Examples

See plugins/examples/ for complete examples:

• wanvideo_extractor.py - WanVideo metadata extraction
• custom_node_extractor.py - Template with documentation

---

Resources

• docs/PLUGIN_SYSTEM_DESIGN.md - Full architecture
• mjr_am_backend/features/metadata/plugin_system/base.py - API reference
• plugins/README.md - Installation guide

Majoor Assets Manager - Plugin System Design Document

Document Type: Architecture Design Version: 1.0.0 Date: March 16, 2026 Author: Architecture Team Status: ✅ Implemented (as of April 2026, v2.4.4+)

Note: This design has been fully implemented. See <code>PLUGIN_SYSTEM_IMPLEMENTATION_SUMMARY.md</code> for implementation details and <code>PLUGIN_QUICK_REFERENCE.md</code> for developer quick reference.

---

📋 Table of Contents

1. Executive Summary
2. Current Architecture Analysis
3. Plugin System Architecture
4. Implementation Plan
5. API Reference
6. Security Model
7. Testing Strategy
8. Migration Guide
9. Appendices

---

📌 Executive Summary

Objective

Design and implement a plugin system for the Majoor Assets Manager that allows third-party developers to create custom metadata extractors without modifying the core codebase.

Problem Statement

The current metadata extraction system is hardcoded with fixed extractors for known formats (PNG, WEBP, video, audio). This creates limitations:

• ❌ Cannot extract custom node-specific metadata (WanVideo, rgthree, etc.)
• ❌ Cannot support new file formats without code changes
• ❌ Cannot add custom parsing logic for proprietary schemas
• ❌ Requires core codebase modification for any new extractor

Solution

Implement a plugin architecture with:

• ✅ Well-defined plugin interface (abstract base class)
• ✅ Auto-discovery mechanism (scan plugin directories)
• ✅ Priority-based extractor selection
• ✅ Sandboxed execution environment
• ✅ Hot-reload capability for development

Benefits

---

🔍 Current Architecture Analysis

Current Metadata Extraction Flow

┌─────────────────────────────────────────────────────────────────┐
│                    MetadataService.extract()                     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  File Type Detection (image/video/audio/3d)                      │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Hardcoded Extractor Lookup                                      │
│  - extract_png_metadata()                                        │
│  - extract_webp_metadata()                                       │
│  - extract_video_metadata()                                      │
│  - extract_audio_metadata()                                      │
│  - extract_3d_model_metadata()                                   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Metadata Normalization & Storage                                │
└─────────────────────────────────────────────────────────────────┘

Current Extractor Registry

File: mjr_am_backend/features/metadata/extractor_registry.py

# Current implementation - hardcoded extractors

EXTRACTORS = {
    "png": extract_png_metadata,
    "webp": extract_webp_metadata,
    "video": extract_video_metadata,
    "audio": extract_audio_metadata,
    "model3d": extract_3d_model_metadata,
}

def get_extractor(file_type: str):
    return EXTRACTORS.get(file_type)

Limitations Identified

1. No Extension Points - Cannot inject custom extractors
2. Tight Coupling - Extractors imported directly in service
3. No Priority System - All extractors treated equally
4. No Validation - No plugin safety checks
5. No Discovery - Manual registration required

---

🏗️ Plugin System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     ComfyUI Runtime                              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   Majoor Assets Manager                          │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │              MetadataService (Modified)                     │ │
│  │   ┌──────────────────────────────────────────────────────┐ │ │
│  │   │           PluginLoader (NEW)                          │ │ │
│  │   │   - discover_plugins()                                │ │ │
│  │   │   - validate_plugins()                                │ │ │
│  │   │   - get_extractor(filepath)                           │ │ │
│  │   └──────────────────────────────────────────────────────┘ │ │
│  │   ┌──────────────────────────────────────────────────────┐ │ │
│  │   │           Built-in Extractors                         │ │ │
│  │   │   - PNG/WEBP extractor                                │ │ │
│  │   │   - Video extractor (FFprobe)                         │ │ │
│  │   │   - Audio extractor                                   │ │ │
│  │   └──────────────────────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Plugin Directory                              │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐ │
│  │ wanvideo_plugin  │  │ rgthree_plugin   │  │ custom_plugin │ │
│  │ ──────────────── │  │ ──────────────── │  │ ───────────── │ │
│  │ priority: 100    │  │ priority: 50     │  │ priority: 10  │ │
│  │ extensions: .png │  │ extensions: .png │  │ extensions:   │ │
│  └──────────────────┘  └──────────────────┘  └───────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Component Diagram

┌─────────────────────────────────────────────────────────────────┐
│                     Plugin System Components                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌────────────────────┐                                         │
│  │  Plugin Interface  │  Abstract base class defining contract  │
│  │  (ABC)             │                                         │
│  └─────────┬──────────┘                                         │
│            │                                                     │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │  Plugin Loader     │  Discovery, validation, loading         │
│  └─────────┬──────────┘                                         │
│            │                                                     │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │  Plugin Registry   │  Runtime registry of loaded plugins     │
│  └─────────┬──────────┘                                         │
│            │                                                     │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │  Plugin Manager    │  Lifecycle management, hot-reload       │
│  └─────────┬──────────┘                                         │
│            │                                                     │
│            ▼                                                     │
│  ┌────────────────────┐                                         │
│  │  Security Validator│  Sandboxing, permission checks          │
│  └────────────────────┘                                         │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Directory Structure

ComfyUI-Majoor-AssetsManager/
├── mjr_am_backend/
│   └── features/
│       └── metadata/
│           ├── service.py                 # Modified to use plugins
│           ├── extractor_registry.py      # Keep built-in extractors
│           └── plugin_system/             # NEW: Plugin system
│               ├── __init__.py
│               ├── base.py                # Plugin interface (ABC)
│               ├── loader.py              # Plugin discovery & loading
│               ├── registry.py            # Runtime plugin registry
│               ├── manager.py             # Lifecycle management
│               ├── validator.py           # Security validation
│               └── sandbox.py             # Execution sandboxing
│
├── plugins/                               # NEW: Plugin directory
│   ├── __init__.py
│   ├── README.md
│   └── examples/
│       ├── wanvideo_extractor.py
│       ├── rgthree_extractor.py
│       └── custom_node_extractor.py
│
├── tests/
│   └── plugins/                           # NEW: Plugin tests
│       ├── test_plugin_loader.py
│       ├── test_plugin_validator.py
│       └── test_plugin_integration.py
│
└── docs/
    └── PLUGIN_DEVELOPMENT_GUIDE.md       # NEW: Plugin dev guide

---

🛠️ Implementation Plan

Phase 1: Core Infrastructure (Week 1)

1.1 Define Plugin Interface

File: mjr_am_backend/features/metadata/plugin_system/base.py

"""
Plugin System - Base Interface

Defines the abstract base class for metadata extractor plugins.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any, Dict, List, Optional
import logging

logger = logging.getLogger(__name__)


@dataclass
class ExtractorMetadata:
    """Metadata about an extractor plugin."""
    name: str
    version: str = "1.0.0"
    author: str = "Unknown"
    description: str = ""
    homepage: str = ""
    license: str = "MIT"


@dataclass
class ExtractionResult:
    """Result from metadata extraction."""
    success: bool
    data: Dict[str, Any] = field(default_factory=dict)
    error: Optional[str] = None
    extractor_name: str = ""
    confidence: float = 1.0  # 0.0-1.0, for fuzzy matching


class MetadataExtractorPlugin(ABC):
    """
    Abstract base class for metadata extractor plugins.

    All plugins must inherit from this class and implement
    the required methods.

    Example:
        class MyExtractor(MetadataExtractorPlugin):
            @property
            def name(self): return "my_extractor"

            @property
            def supported_extensions(self): return ['.png', '.webp']

            async def extract(self, filepath): ...
    """

    # ─── Required Properties ───────────────────────────────────────

    @property
    @abstractmethod
    def name(self) -> str:
        """
        Unique plugin identifier.

        Must be lowercase, alphanumeric with underscores.
        Example: "wanvideo_extractor", "rgthree_extractor"
        """
        pass

    @property
    @abstractmethod
    def supported_extensions(self) -> List[str]:
        """
        File extensions this extractor handles.

        Returns:
            List of extensions including dot, e.g., ['.png', '.webp']
        """
        pass

    @property
    @abstractmethod
    def priority(self) -> int:
        """
        Extraction priority (higher = runs first).

        Priority levels:
        - 100-999: Custom node-specific extractors
        - 50-99:   Format-specific extractors
        - 1-49:    Generic/fallback extractors
        """
        pass

    # ─── Optional Properties ───────────────────────────────────────

    @property
    def metadata(self) -> ExtractorMetadata:
        """Plugin metadata (optional, provides defaults)."""
        return ExtractorMetadata(name=self.name)

    @property
    def min_compatibility_version(self) -> str:
        """Minimum Majoor version required (default: "2.4.5")."""
        return "2.4.5"

    # ─── Required Methods ──────────────────────────────────────────

    @abstractmethod
    async def extract(self, filepath: str) -> ExtractionResult:
        """
        Extract metadata from file.

        Args:
            filepath: Absolute path to file

        Returns:
            ExtractionResult with success status and data

        Raises:
            Any exceptions should be caught and returned as
            ExtractionResult(success=False, error=str(exc))
        """
        pass

    # ─── Optional Methods ──────────────────────────────────────────

    def can_extract(self, filepath: str) -> bool:
        """
        Check if this extractor can handle the file.

        Default implementation checks file extension.
        Override for more complex detection logic.
        """
        ext = Path(filepath).suffix.lower()
        return ext in self.supported_extensions

    async def pre_extract(self, filepath: str) -> bool:
        """
        Pre-extraction hook (optional).

        Called before extract(). Return False to skip extraction.
        Useful for quick validation checks.
        """
        return True

    async def post_extract(
        self,
        filepath: str,
        result: ExtractionResult
    ) -> ExtractionResult:
        """
        Post-extraction hook (optional).

        Called after extract(). Can modify result.
        Useful for cleanup or data enrichment.
        """
        return result

    async def cleanup(self) -> None:
        """
        Cleanup hook called on plugin unload.

        Override to release resources, close connections, etc.
        """
        pass

    # ─── Helper Methods ────────────────────────────────────────────

    def _create_success_result(
        self,
        data: Dict[str, Any],
        confidence: float = 1.0
    ) -> ExtractionResult:
        """Helper to create success result."""
        return ExtractionResult(
            success=True,
            data=data,
            extractor_name=self.name,
            confidence=confidence
        )

    def _create_error_result(
        self,
        error: str
    ) -> ExtractionResult:
        """Helper to create error result."""
        return ExtractionResult(
            success=False,
            error=error,
            extractor_name=self.name
        )

1.2 Implement Plugin Loader

File: mjr_am_backend/features/metadata/plugin_system/loader.py

"""
Plugin System - Loader

Discovers, validates, and loads plugins from configured directories.
"""

from __future__ import annotations

import importlib
import importlib.util
import pkgutil
import sys
from pathlib import Path
from typing import Dict, List, Optional, Set, Type
import logging

from .base import MetadataExtractorPlugin, ExtractorMetadata

logger = logging.getLogger(__name__)


class PluginLoadError(Exception):
    """Raised when plugin loading fails."""
    pass


class PluginLoader:
    """
    Discovers and loads metadata extractor plugins.

    Usage:
        loader = PluginLoader([Path("/plugins")])
        loader.discover_plugins()
        extractor = loader.get_extractor("image.png")
        result = await extractor.extract("image.png")
    """

    def __init__(
        self,
        plugin_dirs: Optional[List[Path]] = None,
        auto_discover: bool = True
    ):
        """
        Initialize plugin loader.

        Args:
            plugin_dirs: Directories to scan for plugins
            auto_discover: Automatically discover on init
        """
        self.plugin_dirs = plugin_dirs or self._default_plugin_dirs()
        self._extractors: Dict[str, MetadataExtractorPlugin] = {}
        self._loaded_modules: Set[str] = set()
        self._load_errors: List[tuple[str, str]] = []

        if auto_discover:
            self.discover_plugins()

    def _default_plugin_dirs(self) -> List[Path]:
        """Get default plugin directories."""
        from ...config import OUTPUT_ROOT_PATH

        return [
            # Bundled plugins
            Path(__file__).parent.parent.parent.parent / "plugins",
            # User plugins (global)
            Path.home() / ".comfyui" / "majoor_plugins" / "extractors",
            # User plugins (local to ComfyUI)
            OUTPUT_ROOT_PATH / "_mjr_plugins" / "extractors",
        ]

    def discover_plugins(self) -> int:
        """
        Scan plugin directories and load all valid extractors.

        Returns:
            Number of plugins successfully loaded
        """
        loaded_count = 0

        for plugin_dir in self.plugin_dirs:
            if not plugin_dir.exists():
                logger.debug(f"Plugin directory does not exist: {plugin_dir}")
                continue

            if not plugin_dir.is_dir():
                logger.warning(f"Plugin path is not a directory: {plugin_dir}")
                continue

            try:
                count = self._scan_directory(plugin_dir)
                loaded_count += count
                logger.info(f"Loaded {count} plugins from {plugin_dir}")
            except Exception as e:
                logger.error(f"Failed to scan {plugin_dir}: {e}")
                self._load_errors.append((str(plugin_dir), str(e)))

        logger.info(f"Total plugins loaded: {loaded_count}")
        return loaded_count

    def _scan_directory(self, directory: Path) -> int:
        """Scan a single directory for plugins."""
        count = 0

        # Scan .py files
        for module_file in directory.glob("*.py"):
            if module_file.name.startswith("_"):
                continue

            try:
                self._load_module(module_file)
                count += 1
            except Exception as e:
                logger.error(f"Failed to load {module_file}: {e}")
                self._load_errors.append((str(module_file), str(e)))

        # Scan subdirectories as packages
        for subdir in directory.iterdir():
            if not subdir.is_dir():
                continue
            if subdir.name.startswith("_"):
                continue
            if not (subdir / "__init__.py").exists():
                continue

            try:
                count += self._scan_package(subdir)
            except Exception as e:
                logger.error(f"Failed to scan package {subdir}: {e}")

        return count

    def _scan_package(self, package_dir: Path) -> int:
        """Scan a package directory for plugins."""
        count = 0
        package_name = package_dir.name

        for module_file in package_dir.glob("*.py"):
            if module_file.name.startswith("_"):
                continue
            if module_file.name == "__init__.py":
                continue

            try:
                self._load_module(module_file, package_name=package_name)
                count += 1
            except Exception as e:
                logger.error(f"Failed to load {module_file}: {e}")

        return count

    def _load_module(
        self,
        module_file: Path,
        package_name: Optional[str] = None
    ) -> None:
        """Load a single Python module and extract plugins."""
        module_name = module_file.stem
        full_name = f"majoor_plugins.{package_name}.{module_name}" if package_name else f"majoor_plugins.{module_name}"

        # Skip already loaded modules
        if full_name in self._loaded_modules:
            return

        # Load module
        spec = importlib.util.spec_from_file_location(full_name, module_file)
        if spec is None or spec.loader is None:
            raise PluginLoadError(f"Cannot load spec for {module_file}")

        module = importlib.util.module_from_spec(spec)
        sys.modules[full_name] = module
        spec.loader.exec_module(module)

        self._loaded_modules.add(full_name)

        # Find and instantiate all extractor classes
        for attr_name in dir(module):
            attr = getattr(module, attr_name)
            if self._is_valid_extractor_class(attr):
                try:
                    extractor = attr()
                    self.register_extractor(extractor)
                except Exception as e:
                    logger.error(f"Failed to instantiate {attr_name}: {e}")

    def _is_valid_extractor_class(self, cls: Type) -> bool:
        """Check if class is a valid extractor plugin."""
        try:
            return (
                isinstance(cls, type) and
                issubclass(cls, MetadataExtractorPlugin) and
                cls is not MetadataExtractorPlugin
            )
        except TypeError:
            return False

    def register_extractor(
        self,
        extractor: MetadataExtractorPlugin,
        force: bool = False
    ) -> None:
        """
        Register an extractor instance.

        Args:
            extractor: Extractor instance to register
            force: Overwrite existing extractor with same name
        """
        name = extractor.name

        if name in self._extractors and not force:
            logger.warning(f"Extractor '{name}' already registered, skipping")
            return

        self._extractors[name] = extractor
        logger.debug(f"Registered extractor: {name}")

    def unregister_extractor(self, name: str) -> bool:
        """
        Unregister an extractor by name.

        Returns:
            True if extractor was found and removed
        """
        if name not in self._extractors:
            return False

        extractor = self._extractors.pop(name)
        try:
            # Call cleanup hook
            import asyncio
            loop = asyncio.get_event_loop()
            loop.run_until_complete(extractor.cleanup())
        except Exception as e:
            logger.error(f"Cleanup failed for {name}: {e}")

        logger.debug(f"Unregistered extractor: {name}")
        return True

    def get_extractor(self, filepath: str) -> Optional[MetadataExtractorPlugin]:
        """
        Get the best extractor for a file (by priority).

        Args:
            filepath: Path to file

        Returns:
            Best matching extractor or None
        """
        matching = [
            ext for ext in self._extractors.values()
            if ext.can_extract(filepath)
        ]

        if not matching:
            return None

        # Return highest priority extractor
        return max(matching, key=lambda e: e.priority)

    def get_extractor_by_name(self, name: str) -> Optional[MetadataExtractorPlugin]:
        """Get extractor by name."""
        return self._extractors.get(name)

    @property
    def all_extractors(self) -> List[MetadataExtractorPlugin]:
        """Get all registered extractors (sorted by priority)."""
        return sorted(
            self._extractors.values(),
            key=lambda e: e.priority,
            reverse=True
        )

    @property
    def extractor_names(self) -> List[str]:
        """Get names of all registered extractors."""
        return list(self._extractors.keys())

    @property
    def load_errors(self) -> List[tuple[str, str]]:
        """Get list of (path, error) tuples for failed loads."""
        return self._load_errors.copy()

    def get_stats(self) -> Dict[str, any]:
        """Get loader statistics."""
        return {
            "total_extractors": len(self._extractors),
            "loaded_modules": len(self._loaded_modules),
            "load_errors": len(self._load_errors),
            "plugin_dirs": [str(d) for d in self.plugin_dirs],
        }

1.3 Implement Plugin Registry

File: mjr_am_backend/features/metadata/plugin_system/registry.py

"""
Plugin System - Registry

Runtime registry for plugin state and configuration.
"""

from __future__ import annotations

import json
from dataclasses import dataclass, field, asdict
from pathlib import Path
from typing import Any, Dict, List, Optional
import logging

from .base import MetadataExtractorPlugin, ExtractorMetadata

logger = logging.getLogger(__name__)


@dataclass
class PluginState:
    """Runtime state of a plugin."""
    name: str
    version: str
    enabled: bool = True
    load_order: int = 0
    error_count: int = 0
    last_error: Optional[str] = None
    extraction_count: int = 0
    avg_confidence: float = 0.0


class PluginRegistry:
    """
    Runtime registry for plugin state and configuration.

    Persists plugin configuration and tracks runtime statistics.
    """

    def __init__(self, config_path: Optional[Path] = None):
        """
        Initialize registry.

        Args:
            config_path: Path to persist configuration (optional)
        """
        self.config_path = config_path
        self._plugin_states: Dict[str, PluginState] = {}
        self._load_order_counter = 0

        if config_path and config_path.exists():
            self._load_config()

    def register_plugin(
        self,
        plugin: MetadataExtractorPlugin,
        enabled: bool = True
    ) -> None:
        """Register a plugin with state tracking."""
        name = plugin.name

        if name in self._plugin_states:
            state = self._plugin_states[name]
            state.version = plugin.metadata.version
        else:
            state = PluginState(
                name=name,
                version=plugin.metadata.version,
                enabled=enabled,
                load_order=self._load_order_counter
            )
            self._load_order_counter += 1
            self._plugin_states[name] = state

    def unregister_plugin(self, name: str) -> None:
        """Unregister a plugin."""
        if name in self._plugin_states:
            del self._plugin_states[name]

    def enable_plugin(self, name: str) -> bool:
        """Enable a plugin."""
        if name not in self._plugin_states:
            return False
        self._plugin_states[name].enabled = True
        self._save_config()
        return True

    def disable_plugin(self, name: str) -> bool:
        """Disable a plugin."""
        if name not in self._plugin_states:
            return False
        self._plugin_states[name].enabled = False
        self._save_config()
        return True

    def is_enabled(self, name: str) -> bool:
        """Check if plugin is enabled."""
        if name not in self._plugin_states:
            return False
        return self._plugin_states[name].enabled

    def record_error(self, name: str, error: str) -> None:
        """Record an error for a plugin."""
        if name not in self._plugin_states:
            return
        state = self._plugin_states[name]
        state.error_count += 1
        state.last_error = error

    def record_extraction(
        self,
        name: str,
        confidence: float = 1.0
    ) -> None:
        """Record a successful extraction."""
        if name not in self._plugin_states:
            return
        state = self._plugin_states[name]
        state.extraction_count += 1
        # Running average of confidence
        total = state.extraction_count
        state.avg_confidence = (
            (state.avg_confidence * (total - 1) + confidence) / total
        )

    def get_state(self, name: str) -> Optional[PluginState]:
        """Get state for a plugin."""
        return self._plugin_states.get(name)

    def get_all_states(self) -> List[PluginState]:
        """Get all plugin states."""
        return list(self._plugin_states.values())

    def get_enabled_plugins(self) -> List[PluginState]:
        """Get states for enabled plugins only."""
        return [s for s in self._plugin_states.values() if s.enabled]

    def _load_config(self) -> None:
        """Load configuration from disk."""
        try:
            data = json.loads(self.config_path.read_text())
            for name, state_data in data.get("plugins", {}).items():
                self._plugin_states[name] = PluginState(**state_data)
            logger.info(f"Loaded plugin config from {self.config_path}")
        except Exception as e:
            logger.warning(f"Failed to load plugin config: {e}")

    def _save_config(self) -> None:
        """Save configuration to disk."""
        if not self.config_path:
            return

        try:
            data = {
                "plugins": {
                    name: asdict(state)
                    for name, state in self._plugin_states.items()
                }
            }
            self.config_path.parent.mkdir(parents=True, exist_ok=True)
            self.config_path.write_text(json.dumps(data, indent=2))
        except Exception as e:
            logger.warning(f"Failed to save plugin config: {e}")

    def get_stats(self) -> Dict[str, Any]:
        """Get registry statistics."""
        states = self.get_all_states()
        return {
            "total_plugins": len(states),
            "enabled_plugins": len(self.get_enabled_plugins()),
            "total_extractions": sum(s.extraction_count for s in states),
            "total_errors": sum(s.error_count for s in states),
        }

---

Phase 2: Integration (Week 2)

2.1 Modify MetadataService

File: mjr_am_backend/features/metadata/service.py

"""Metadata extraction service - Modified for plugin support."""

from __future__ import annotations

from pathlib import Path
from typing import Any, Dict, Optional
import logging

from .plugin_system.loader import PluginLoader
from .plugin_system.registry import PluginRegistry
from .extractors import extract_png_metadata, extract_webp_metadata
from ...config import INDEX_DIR_PATH

logger = logging.getLogger(__name__)


class MetadataService:
    """
    Metadata extraction service with plugin support.

    Orchestrates extraction using both built-in extractors
    and plugin-based extractors.
    """

    def __init__(
        self,
        exiftool,
        ffprobe,
        settings,
        plugin_dirs: Optional[list] = None
    ):
        self.exiftool = exiftool
        self.ffprobe = ffprobe
        self.settings = settings

        # Initialize plugin system
        plugin_config_path = INDEX_DIR_PATH / "plugin_config.json"
        self.plugin_registry = PluginRegistry(plugin_config_path)
        self.plugin_loader = PluginLoader(
            plugin_dirs=plugin_dirs,
            auto_discover=True
        )

        logger.info(
            f"MetadataService initialized with "
            f"{len(self.plugin_loader.all_extractors)} plugin extractors"
        )

    async def extract_metadata(
        self,
        filepath: str,
        file_type: str
    ) -> Dict[str, Any]:
        """
        Extract metadata from file using plugin system.

        Priority:
        1. Plugin extractors (by priority order)
        2. Built-in extractors (fallback)

        Args:
            filepath: Absolute path to file
            file_type: File type (image, video, audio, model3d)

        Returns:
            Dict with extracted metadata
        """
        filepath = str(filepath).strip()

        # 1. Try plugin extractors first (by priority)
        plugin_result = await self._extract_with_plugins(filepath)
        if plugin_result and plugin_result.get("success"):
            logger.debug(
                f"Plugin extraction successful for {filepath} "
                f"(extractor: {plugin_result.get('extractor')})"
            )
            return plugin_result.get("data", {})

        # 2. Fallback to built-in extractors
        logger.debug(f"Falling back to built-in extractor for {filepath}")
        return await self._extract_with_builtin(filepath, file_type)

    async def _extract_with_plugins(
        self,
        filepath: str
    ) -> Optional[Dict[str, Any]]:
        """Try extraction with plugin extractors."""
        extractor = self.plugin_loader.get_extractor(filepath)

        if not extractor:
            return None

        plugin_name = extractor.name

        # Check if plugin is enabled
        if not self.plugin_registry.is_enabled(plugin_name):
            logger.debug(f"Plugin {plugin_name} is disabled, skipping")
            return None

        try:
            # Pre-extraction hook
            if not await extractor.pre_extract(filepath):
                logger.debug(f"Plugin {plugin_name} pre_extract returned False")
                return None

            # Extract
            result = await extractor.extract(filepath)

            if result.success:
                # Record success
                self.plugin_registry.record_extraction(
                    plugin_name,
                    result.confidence
                )

                # Post-extraction hook
                result = await extractor.post_extract(filepath, result)

                return {
                    "success": True,
                    "data": result.data,
                    "extractor": plugin_name,
                    "confidence": result.confidence,
                }
            else:
                # Record error
                self.plugin_registry.record_error(
                    plugin_name,
                    result.error or "Unknown error"
                )
                logger.warning(
                    f"Plugin {plugin_name} extraction failed: {result.error}"
                )
                return None

        except Exception as e:
            logger.exception(f"Plugin {plugin_name} raised exception: {e}")
            self.plugin_registry.record_error(plugin_name, str(e))
            return None

    async def _extract_with_builtin(
        self,
        filepath: str,
        file_type: str
    ) -> Dict[str, Any]:
        """Extract using built-in extractors."""
        try:
            ext = Path(filepath).suffix.lower()

            if ext in ['.png']:
                data = await extract_png_metadata(
                    filepath, self.exiftool, self.ffprobe
                )
            elif ext in ['.webp', '.gif']:
                data = await extract_webp_metadata(
                    filepath, self.exiftool, self.ffprobe
                )
            elif file_type == 'video':
                data = await extract_video_metadata(
                    filepath, self.ffprobe
                )
            elif file_type == 'audio':
                data = await extract_audio_metadata(
                    filepath, self.ffprobe
                )
            elif file_type == 'model3d':
                data = await extract_3d_model_metadata(filepath)
            else:
                data = {"success": False, "error": "No extractor available"}

            return data

        except Exception as e:
            logger.exception(f"Built-in extraction failed: {e}")
            return {
                "success": False,
                "error": str(e),
                "extractor": "builtin"
            }

    def get_plugin_stats(self) -> Dict[str, Any]:
        """Get plugin system statistics."""
        return {
            "loader": self.plugin_loader.get_stats(),
            "registry": self.plugin_registry.get_stats(),
        }

    def enable_plugin(self, name: str) -> bool:
        """Enable a plugin by name."""
        return self.plugin_registry.enable_plugin(name)

    def disable_plugin(self, name: str) -> bool:
        """Disable a plugin by name."""
        return self.plugin_registry.disable_plugin(name)

    def list_plugins(self) -> list:
        """List all registered plugins with state."""
        plugins = []
        for extractor in self.plugin_loader.all_extractors:
            state = self.plugin_registry.get_state(extractor.name)
            plugins.append({
                "name": extractor.name,
                "version": extractor.metadata.version,
                "enabled": state.enabled if state else True,
                "priority": extractor.priority,
                "extensions": extractor.supported_extensions,
                "extractions": state.extraction_count if state else 0,
                "errors": state.error_count if state else 0,
            })
        return plugins

2.2 Add Plugin Management Routes

File: mjr_am_backend/routes/handlers/plugins.py

"""Plugin management API routes."""

from aiohttp import web
from ...shared import Result, get_logger

logger = get_logger(__name__)


def register_plugin_routes(routes: web.RouteTableDef) -> None:
    """Register plugin management routes."""

    @routes.get("/mjr/am/plugins/list")
    async def list_plugins(request: web.Request) -> web.Response:
        """List all registered plugins."""
        try:
            services = request.app["services"]
            metadata_service = services.get("metadata")

            if not metadata_service:
                return web.json_response({
                    "ok": False,
                    "error": "Metadata service not available"
                })

            plugins = metadata_service.list_plugins()
            stats = metadata_service.get_plugin_stats()

            return web.json_response({
                "ok": True,
                "data": {
                    "plugins": plugins,
                    "stats": stats
                }
            })

        except Exception as e:
            logger.exception("Failed to list plugins")
            return web.json_response({
                "ok": False,
                "error": str(e)
            }, status=500)

    @routes.post("/mjr/am/plugins/{name}/enable")
    async def enable_plugin(request: web.Request) -> web.Response:
        """Enable a plugin."""
        try:
            name = request.match_info["name"]
            services = request.app["services"]
            metadata_service = services.get("metadata")

            if not metadata_service:
                return web.json_response({
                    "ok": False,
                    "error": "Metadata service not available"
                })

            success = metadata_service.enable_plugin(name)

            return web.json_response({
                "ok": success,
                "data": {"enabled": success}
            })

        except Exception as e:
            logger.exception(f"Failed to enable plugin {name}")
            return web.json_response({
                "ok": False,
                "error": str(e)
            }, status=500)

    @routes.post("/mjr/am/plugins/{name}/disable")
    async def disable_plugin(request: web.Request) -> web.Response:
        """Disable a plugin."""
        try:
            name = request.match_info["name"]
            services = request.app["services"]
            metadata_service = services.get("metadata")

            if not metadata_service:
                return web.json_response({
                    "ok": False,
                    "error": "Metadata service not available"
                })

            success = metadata_service.disable_plugin(name)

            return web.json_response({
                "ok": success,
                "data": {"enabled": not success}
            })

        except Exception as e:
            logger.exception(f"Failed to disable plugin {name}")
            return web.json_response({
                "ok": False,
                "error": str(e)
            }, status=500)

    @routes.post("/mjr/am/plugins/reload")
    async def reload_plugins(request: web.Request) -> web.Response:
        """Reload all plugins (hot-reload)."""
        try:
            services = request.app["services"]
            metadata_service = services.get("metadata")

            if not metadata_service:
                return web.json_response({
                    "ok": False,
                    "error": "Metadata service not available"
                })

            # Rediscover plugins
            count = metadata_service.plugin_loader.discover_plugins()

            return web.json_response({
                "ok": True,
                "data": {
                    "reloaded": count,
                    "message": f"Reloaded {count} plugins"
                }
            })

        except Exception as e:
            logger.exception("Failed to reload plugins")
            return web.json_response({
                "ok": False,
                "error": str(e)
            }, status=500)

---

Phase 3: Example Plugins (Week 3)

3.1 WanVideo Extractor Plugin

File: plugins/examples/wanvideo_extractor.py

"""
WanVideo Metadata Extractor Plugin

Extracts WanVideo-specific metadata from generated images.
WanVideo stores custom parameters in PNG text chunks.
"""

from __future__ import annotations

from pathlib import Path
from typing import Any, Dict
import json
import logging

# Import from plugin system
from mjr_am_backend.features.metadata.plugin_system.base import (
    MetadataExtractorPlugin,
    ExtractionResult,
    ExtractorMetadata,
)

logger = logging.getLogger(__name__)


class WanVideoExtractor(MetadataExtractorPlugin):
    """Extractor for WanVideo custom node metadata."""

    @property
    def name(self) -> str:
        return "wanvideo_extractor"

    @property
    def supported_extensions(self) -> list[str]:
        return ['.png', '.webp']

    @property
    def priority(self) -> int:
        return 100  # High priority - runs before generic extractors

    @property
    def metadata(self) -> ExtractorMetadata:
        return ExtractorMetadata(
            name=self.name,
            version="1.0.0",
            author="Majoor Team",
            description="Extract WanVideo metadata from PNG/WebP files",
            homepage="https://github.com/MajoorWaldi/ComfyUI-Majoor-AssetsManager",
            license="MIT"
        )

    async def extract(self, filepath: str) -> ExtractionResult:
        """Extract WanVideo metadata."""
        try:
            from PIL import Image

            result_data = {
                "prompt": None,
                "negative_prompt": None,
                "seed": None,
                "steps": None,
                "sampler": None,
                "cfg": None,
                "models": [],
                "loras": [],
                "custom_data": {
                    "wan_version": None,
                    "motion_bucket_id": None,
                    "fps": None,
                    "aug_level": None,
                    "source_type": None,
                }
            }

            img = None
            try:
                img = Image.open(filepath)

                # Check for WanVideo-specific PNG chunks
                wan_data = None

                if "wanv2" in img.info:
                    wan_data = json.loads(img.info["wanv2"])
                elif "wanvideo" in img.info:
                    wan_data = json.loads(img.info["wanvideo"])

                if wan_data:
                    result_data["custom_data"].update({
                        "wan_version": wan_data.get("version"),
                        "motion_bucket_id": wan_data.get("motion_bucket_id"),
                        "fps": wan_data.get("fps"),
                        "aug_level": wan_data.get("aug_level"),
                        "source_type": wan_data.get("source_type"),
                    })

                # Also extract standard ComfyUI metadata
                if "parameters" in img.info:
                    param_string = img.info["parameters"]
                    parsed = self._parse_parameters(param_string)
                    result_data.update(parsed)

                img.close()

            except Exception as e:
                if img:
                    img.close()
                raise

            return self._create_success_result(result_data, confidence=0.95)

        except Exception as e:
            logger.exception(f"WanVideo extraction failed for {filepath}")
            return self._create_error_result(str(e))

    def _parse_parameters(self, param_string: str) -> Dict[str, Any]:
        """Parse ComfyUI parameter string."""
        # Implementation for parsing standard ComfyUI metadata
        # This is simplified - use existing parser from extractors.py
        result = {}

        try:
            lines = param_string.split('\n')
            for line in lines:
                if ':' in line:
                    key, value = line.split(':', 1)
                    key = key.strip().lower()
                    value = value.strip()

                    if key == 'seed':
                        result['seed'] = int(value)
                    elif key == 'steps':
                        result['steps'] = int(value)
                    elif key == 'cfg':
                        result['cfg'] = float(value)
                    elif key == 'sampler':
                        result['sampler'] = value
        except Exception:
            pass

        return result

3.2 rgthree Extractor Plugin

File: plugins/examples/rgthree_extractor.py

"""
rgthree Metadata Extractor Plugin

Extracts rgthree custom node metadata including comparison images
and advanced workflow data.
"""

from __future__ import annotations

from typing import Any, Dict
import json
import logging

from mjr_am_backend.features.metadata.plugin_system.base import (
    MetadataExtractorPlugin,
    ExtractionResult,
    ExtractorMetadata,
)

logger = logging.getLogger(__name__)


class RgthreeExtractor(MetadataExtractorPlugin):
    """Extractor for rgthree custom node metadata."""

    @property
    def name(self) -> str:
        return "rgthree_extractor"

    @property
    def supported_extensions(self) -> list[str]:
        return ['.png', '.json']

    @property
    def priority(self) -> int:
        return 50

    @property
    def metadata(self) -> ExtractorMetadata:
        return ExtractorMetadata(
            name=self.name,
            version="1.0.0",
            author="Majoor Team",
            description="Extract rgthree node metadata",
            license="MIT"
        )

    async def extract(self, filepath: str) -> ExtractionResult:
        """Extract rgthree metadata."""
        try:
            result_data = {
                "custom_data": {
                    "rgthree_nodes": [],
                    "comparison_images": [],
                    "context_mappings": [],
                }
            }

            # Try to extract from PNG metadata
            if filepath.lower().endswith('.png'):
                result_data.update(
                    await self._extract_from_png(filepath)
                )

            # Try to extract from workflow JSON
            elif filepath.lower().endswith('.json'):
                result_data.update(
                    await self._extract_from_json(filepath)
                )

            return self._create_success_result(result_data, confidence=0.85)

        except Exception as e:
            logger.exception(f"rgthree extraction failed for {filepath}")
            return self._create_error_result(str(e))

    async def _extract_from_png(self, filepath: str) -> Dict[str, Any]:
        """Extract rgthree data from PNG."""
        from PIL import Image

        result = {"custom_data": {}}

        try:
            img = Image.open(filepath)

            # Look for rgthree-specific metadata
            if "rgthree" in img.info:
                rgthree_data = json.loads(img.info["rgthree"])
                result["custom_data"]["rgthree_nodes"] = rgthree_data.get("nodes", [])

            img.close()

        except Exception as e:
            logger.debug(f"Failed to extract rgthree PNG data: {e}")

        return result

    async def _extract_from_json(self, filepath: str) -> Dict[str, Any]:
        """Extract rgthree data from workflow JSON."""
        result = {"custom_data": {}}

        try:
            with open(filepath, 'r', encoding='utf-8') as f:
                workflow = json.load(f)

            # Look for rgthree nodes in workflow
            nodes = workflow.get("nodes", [])
            rgthree_nodes = [
                n for n in nodes
                if n.get("type", "").startswith("rgthree.")
            ]

            result["custom_data"]["rgthree_nodes"] = rgthree_nodes

        except Exception as e:
            logger.debug(f"Failed to extract rgthree JSON data: {e}")

        return result

---

Phase 4: Documentation (Week 4)

4.1 Plugin Development Guide

File: docs/PLUGIN_DEVELOPMENT_GUIDE.md

# Plugin Development Guide

## Quick Start

### 1. Create Plugin File

my_plugin.py

from mjr_am_backend.features.metadata.plugin_system.base import ( MetadataExtractorPlugin, ExtractionResult, )

class MyExtractor(MetadataExtractorPlugin): @property def name(self): return "my_extractor"

@property def supported_extensions(self): return ['.png']

@property def priority(self): return 50

async def extract(self, filepath): # Your extraction logic here return self._create_success_result({"key": "value"})

### 2. Install Plugin

Copy to plugin directory:

cp my_plugin.py ~/.comfyui/majoor_plugins/extractors/

### 3. Reload Plugins

In Assets Manager UI: Settings → Plugins → Reload

Or via API:

curl -X POST http://localhost:8188/mjr/am/plugins/reload

## Plugin API Reference

See `base.py` for full API documentation.

## Examples

See `plugins/examples/` for complete examples.

---

🔒 Security Model

Plugin Validation

# mjr_am_backend/features/metadata/plugin_system/validator.py

import ast
import re
from pathlib import Path
from typing import List, Tuple

class PluginValidator:
    """Validates plugins for security issues."""

    DANGEROUS_PATTERNS = [
        r"__import__\s*\(\s*['\"]os['\"]\s*\)",
        r"__import__\s*\(\s*['\"]subprocess['\"]\s*\)",
        r"subprocess\.(call|run|Popen|check_output)",
        r"os\.(system|popen|spawn|exec)",
        r"eval\s*\(",
        r"exec\s*\(",
        r"compile\s*\(",
        r"__builtins__",
        r"importlib\.(reload|import_module)",
    ]

    @classmethod
    def validate(cls, plugin_path: Path) -> Tuple[bool, List[str]]:
        """
        Validate a plugin file.

        Returns:
            (is_valid, list_of_warnings)
        """
        warnings = []

        try:
            content = plugin_path.read_text(encoding='utf-8')
        except Exception as e:
            return False, [f"Cannot read file: {e}"]

        # Pattern-based checks
        for pattern in cls.DANGEROUS_PATTERNS:
            if re.search(pattern, content):
                warnings.append(f"Dangerous pattern detected: {pattern}")

        # AST-based checks
        try:
            tree = ast.parse(content)
            warnings.extend(cls._check_ast(tree))
        except SyntaxError as e:
            return False, [f"Syntax error: {e}"]

        is_valid = len(warnings) == 0
        return is_valid, warnings

    @classmethod
    def _check_ast(cls, tree: ast.AST) -> List[str]:
        """AST-based security checks."""
        warnings = []

        for node in ast.walk(tree):
            # Check for dangerous imports
            if isinstance(node, ast.Import):
                for alias in node.names:
                    if alias.name in ['os', 'subprocess', 'ctypes']:
                        warnings.append(
                            f"Dangerous import: {alias.name}"
                        )

            if isinstance(node, ast.ImportFrom):
                if node.module in ['os', 'subprocess', 'ctypes']:
                    warnings.append(f"Dangerous import from: {node.module}")

        return warnings

Sandboxed Execution

# mjr_am_backend/features/metadata/plugin_system/sandbox.py

import asyncio
import functools
from typing import Any, Callable, TypeVar

T = TypeVar('T')

class ExecutionSandbox:
    """
    Sandboxed execution for plugin methods.

    Limits:
    - Timeout: 30 seconds max
    - Memory: 512MB max (via resource limits on Unix)
    - Filesystem: Read-only access to specified paths
    """

    DEFAULT_TIMEOUT = 30.0  # seconds

    @classmethod
    async def run_with_timeout(
        cls,
        func: Callable,
        *args,
        timeout: float = DEFAULT_TIMEOUT,
        **kwargs
    ) -> T:
        """Run function with timeout."""
        try:
            loop = asyncio.get_event_loop()
            return await asyncio.wait_for(
                loop.run_in_executor(None, functools.partial(func, *args, **kwargs)),
                timeout=timeout
            )
        except asyncio.TimeoutError:
            raise TimeoutError(f"Plugin execution timed out after {timeout}s")

    @classmethod
    def restrict_filesystem(
        cls,
        allowed_paths: list
    ) -> Callable:
        """
        Decorator to restrict filesystem access.

        Usage:
            @restrict_filesystem(['/allowed/path'])
            def extract(self, filepath):
                ...
        """
        def decorator(func: Callable) -> Callable:
            @functools.wraps(func)
            def wrapper(*args, **kwargs):
                # Validate all path arguments
                for arg in args:
                    if isinstance(arg, str):
                        cls._validate_path(arg, allowed_paths)
                for value in kwargs.values():
                    if isinstance(value, str):
                        cls._validate_path(value, allowed_paths)

                return func(*args, **kwargs)
            return wrapper
        return decorator

    @staticmethod
    def _validate_path(path: str, allowed_paths: list) -> None:
        """Validate path is within allowed directories."""
        from pathlib import Path

        resolved = Path(path).resolve()

        for allowed in allowed_paths:
            try:
                resolved.relative_to(Path(allowed).resolve())
                return  # Path is within allowed directory
            except ValueError:
                continue

        raise PermissionError(
            f"Access denied: {path} is outside allowed directories"
        )

---

🧪 Testing Strategy

Unit Tests

# tests/plugins/test_plugin_loader.py

import pytest
from pathlib import Path
from mjr_am_backend.features.metadata.plugin_system.loader import PluginLoader
from mjr_am_backend.features.metadata.plugin_system.base import (
    MetadataExtractorPlugin,
    ExtractionResult,
)


class MockExtractor(MetadataExtractorPlugin):
    @property
    def name(self): return "mock_extractor"

    @property
    def supported_extensions(self): return ['.png']

    @property
    def priority(self): return 50

    async def extract(self, filepath):
        return self._create_success_result({"test": "data"})


class TestPluginLoader:
    @pytest.fixture
    def loader(self, tmp_path):
        return PluginLoader([tmp_path], auto_discover=False)

    def test_register_extractor(self, loader):
        extractor = MockExtractor()
        loader.register_extractor(extractor)

        assert "mock_extractor" in loader.extractor_names
        assert loader.get_extractor_by_name("mock_extractor") is extractor

    def test_get_extractor_by_extension(self, loader):
        loader.register_extractor(MockExtractor())

        extractor = loader.get_extractor("test.png")
        assert extractor is not None
        assert extractor.name == "mock_extractor"

    def test_priority_ordering(self, loader):
        class HighPriority(MockExtractor):
            @property
            def priority(self): return 100

        class LowPriority(MockExtractor):
            @property
            def priority(self): return 10

        loader.register_extractor(LowPriority())
        loader.register_extractor(HighPriority())

        # Should get high priority first
        extractor = loader.get_extractor("test.png")
        assert extractor.priority == 100


# tests/plugins/test_plugin_validator.py

from mjr_am_backend.features.metadata.plugin_system.validator import (
    PluginValidator,
)


class TestPluginValidator:
    def test_safe_plugin(self, tmp_path):
        plugin_file = tmp_path / "safe_plugin.py"
        plugin_file.write_text("""
class SafeExtractor:
    pass
""")

        is_valid, warnings = PluginValidator.validate(plugin_file)
        assert is_valid is True
        assert len(warnings) == 0

    def test_dangerous_import(self, tmp_path):
        plugin_file = tmp_path / "dangerous.py"
        plugin_file.write_text("""
import os
os.system('echo hello')
""")

        is_valid, warnings = PluginValidator.validate(plugin_file)
        assert "Dangerous import: os" in warnings

Integration Tests

# tests/plugins/test_plugin_integration.py

import pytest
from mjr_am_backend.features.metadata.service import MetadataService


class TestPluginIntegration:
    @pytest.fixture
    def metadata_service(self, tmp_path):
        plugin_dir = tmp_path / "plugins"
        plugin_dir.mkdir()

        # Create test plugin
        plugin_file = plugin_dir / "test_extractor.py"
        plugin_file.write_text("""
from mjr_am_backend.features.metadata.plugin_system.base import (
    MetadataExtractorPlugin,
    ExtractionResult,
)

class TestExtractor(MetadataExtractorPlugin):
    @property
    def name(self): return "test_extractor"
    @property
    def supported_extensions(self): return ['.png']
    @property
    def priority(self): return 100
    async def extract(self, filepath):
        return self._create_success_result({"from_plugin": True})
""")

        return MetadataService(
            exiftool=None,
            ffprobe=None,
            settings=None,
            plugin_dirs=[plugin_dir]
        )

    @pytest.mark.asyncio
    async def test_plugin_extraction(self, metadata_service, tmp_path):
        # Create test file
        test_file = tmp_path / "test.png"
        test_file.write_bytes(b"fake png")

        result = await metadata_service.extract_metadata(
            str(test_file),
            "image"
        )

        assert result.get("from_plugin") is True

---

📦 Migration Guide

For Existing Code

Step 1: Update MetadataService Initialization

Before:

metadata_service = MetadataService(exiftool, ffprobe, settings)

After:

metadata_service = MetadataService(
    exiftool,
    ffprobe,
    settings,
    plugin_dirs=None  # Uses defaults
)

Step 2: Update Extractor Calls

Before:

from .extractor_registry import get_extractor

extractor = get_extractor("png")
result = await extractor(filepath)

After:

# No change needed - service handles plugin routing
result = await metadata_service.extract_metadata(filepath, "image")

Step 3: Add Plugin Directory to .gitignore

# Plugin directories
plugins/*.pyc
plugins/__pycache__/
~/.comfyui/majoor_plugins/
output/_mjr_plugins/

For Plugin Developers

Migrating from Custom Forks

If you've created custom extractors by modifying the core codebase:

1. Extract your logic into a plugin class
2. Move to plugin directory (~/.comfyui/majoor_plugins/extractors/)
3. Remove core modifications
4. Test with plugin system

Example Migration:

Before (Core Modification):

# mjr_am_backend/features/metadata/extractors.py
async def extract_my_custom_metadata(filepath):
    # Your custom logic
    pass

After (Plugin):

# ~/.comfyui/majoor_plugins/extractors/my_extractor.py
from mjr_am_backend.features.metadata.plugin_system.base import (
    MetadataExtractorPlugin,
    ExtractionResult,
)

class MyExtractor(MetadataExtractorPlugin):
    @property
    def name(self): return "my_extractor"
    @property
    def supported_extensions(self): return ['.png']
    @property
    def priority(self): return 100

    async def extract(self, filepath):
        # Your custom logic here
        return self._create_success_result({...})

---

📊 Performance Considerations

Plugin Loading

• Cold Start: 100-500ms for 10 plugins
• Hot Reload: 50-200ms
• Memory: ~5-10MB per plugin

Extraction Overhead

• Plugin Routing: <1ms per file
• Priority Sorting: Cached, negligible
• Fallback Chain: Adds 2-5ms if plugins fail

Optimization Strategies

# 1. Lazy loading - plugins loaded on first use
class LazyPluginLoader:
    def __init__(self):
        self._cache = {}

    def get_extractor(self, filepath):
        ext = Path(filepath).suffix
        if ext not in self._cache:
            self._cache[ext] = self._load_for_extension(ext)
        return self._cache[ext]

# 2. Result caching
from functools import lru_cache

class CachedExtractor:
    @lru_cache(maxsize=1000)
    def extract_cached(self, filepath_hash):
        ...

# 3. Parallel extraction for batch operations
async def extract_batch(filepaths, max_concurrency=4):
    semaphore = asyncio.Semaphore(max_concurrency)

    async def extract_one(fp):
        async with semaphore:
            return await extractor.extract(fp)

    return await asyncio.gather(*[extract_one(fp) for fp in filepaths])

---

🎯 Success Metrics

---

📝 Appendices

A. Plugin Template

"""
[Plugin Name] Extractor

[Description]
"""

from mjr_am_backend.features.metadata.plugin_system.base import (
    MetadataExtractorPlugin,
    ExtractionResult,
    ExtractorMetadata,
)


class [PluginName]Extractor(MetadataExtractorPlugin):
    @property
    def name(self) -> str:
        return "[plugin_name]_extractor"

    @property
    def supported_extensions(self) -> list[str]:
        return ['.png', '.webp']

    @property
    def priority(self) -> int:
        return 50

    @property
    def metadata(self) -> ExtractorMetadata:
        return ExtractorMetadata(
            name=self.name,
            version="1.0.0",
            author="Your Name",
            description="Your description",
            license="MIT"
        )

    async def extract(self, filepath: str) -> ExtractionResult:
        try:
            # Your extraction logic
            data = {}
            return self._create_success_result(data)
        except Exception as e:
            return self._create_error_result(str(e))

B. Environment Variables

# Plugin directories (colon-separated on Unix, semicolon on Windows)
MJR_PLUGIN_DIRS=~/.comfyui/majoor_plugins:/opt/majoor_plugins

# Plugin security
MJR_PLUGIN_VALIDATION=strict  # strict, permissive, disabled
MJR_PLUGIN_TIMEOUT=30  # seconds

# Plugin logging
MJR_PLUGIN_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

C. Troubleshooting

---

Document End

Plugin System Implementation Summary

Date: March 16, 2026 Status: Implementation Complete (Ready for Integration)

---

📦 Files Created

Core Plugin System (mjr_am_backend/features/metadata/plugin_system/)

Documentation (docs/)

Example Plugins (plugins/)

Grand Total: ~4,000 lines of code

---

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    Plugin System Architecture                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  MetadataService (Modified)                                 │ │
│  │  - Uses PluginManager for extraction                       │ │
│  │  - Falls back to built-in extractors                       │ │
│  └────────────────────────────────────────────────────────────┘ │
│                              │                                   │
│                              ▼                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  PluginManager                                              │ │
│  │  - initialize()                                             │ │
│  │  - extract(filepath)                                        │ │
│  │  - list_plugins()                                           │ │
│  │  - reload()                                                 │ │
│  └────────────────────────────────────────────────────────────┘ │
│              │                    │                              │
│              ▼                    ▼                              │
│  ┌────────────────────┐  ┌────────────────────┐                 │
│  │  PluginLoader      │  │  PluginRegistry    │                 │
│  │  - discover()      │  │  - enable/disable  │                 │
│  │  - validate()      │  │  - state tracking  │                 │
│  │  - load modules    │  │  - persistence     │                 │
│  └────────────────────┘  └────────────────────┘                 │
│              │                                                   │
│              ▼                                                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │  Loaded Plugins                                             │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │ │
│  │  │ wanvideo     │  │ rgthree      │  │ custom       │     │ │
│  │  │ extractor    │  │ extractor    │  │ extractor    │     │ │
│  │  └──────────────┘  └──────────────┘  └──────────────┘     │ │
│  └────────────────────────────────────────────────────────────┘ │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

🔌 Plugin Interface

Abstract Base Class

from mjr_am_backend.features.metadata.plugin_system.base import (
    MetadataExtractorPlugin,
    ExtractionResult,
)

class MyExtractor(MetadataExtractorPlugin):
    @property
    def name(self) -> str: ...

    @property
    def supported_extensions(self) -> list[str]: ...

    @property
    def priority(self) -> int: ...

    async def extract(self, filepath: str) -> ExtractionResult: ...

Plugin Lifecycle

1. Discovery - Scan plugin directories for .py files
2. Validation - Security check (no eval, exec, os.system, etc.)
3. Loading - Import module, instantiate extractors
4. Registration - Register in loader and registry
5. Runtime - Handle extraction requests
6. Cleanup - Release resources on unload

---

🔒 Security Features

Validation Checks

Blocked Patterns

# Code execution
eval(), exec(), compile()

# OS access
os.system(), os.popen(), subprocess.*

# Network access
socket.*, requests.*, urllib.*

# Unsafe deserialization
pickle.load(), marshal.load()

Validation Modes

• strict - Fail on any warning (default)
• permissive - Fail only on critical issues
• disabled - No validation (not recommended)

---

📊 Features

Plugin Loader

• ✅ Auto-discovery from multiple directories
• ✅ Security validation before loading
• ✅ Priority-based extractor selection
• ✅ Hot-reload support
• ✅ Error tracking and reporting
• ✅ Plugin information tracking

Plugin Registry

• ✅ State persistence (JSON config)
• ✅ Enable/disable plugins
• ✅ Statistics tracking (extractions, errors, confidence)
• ✅ Performance metrics (avg extraction time)
• ✅ Import/export configuration

Plugin Manager

• ✅ Lifecycle management (init, shutdown)
• ✅ Extraction with fallback support
• ✅ Event hooks (on_extract, on_error)
• ✅ Statistics and monitoring
• ✅ Hot-reload capability

---

🔧 Integration Steps

Step 1: Modify MetadataService

# mjr_am_backend/features/metadata/service.py

from .plugin_system.manager import PluginManager

class MetadataService:
    def __init__(self, exiftool, ffprobe, settings, plugin_dirs=None):
        # Existing initialization
        self.exiftool = exiftool
        self.ffprobe = ffprobe
        self.settings = settings

        # NEW: Initialize plugin system
        self.plugin_manager = PluginManager(
            plugin_dirs=plugin_dirs,
            config_path=INDEX_DIR_PATH / "plugin_config.json"
        )

    async def extract_metadata(self, filepath: str, file_type: str):
        # NEW: Try plugin extractors first
        result = await self.plugin_manager.extract(
            filepath,
            fallback_extractor=lambda fp: self._extract_with_builtin(fp, file_type)
        )

        if result.success:
            return result.data

        # Fallback to built-in extractors
        return await self._extract_with_builtin(filepath, file_type)

Step 2: Add API Routes

# mjr_am_backend/routes/handlers/plugins.py

from aiohttp import web

def register_plugin_routes(routes: web.RouteTableDef):
    @routes.get("/mjr/am/plugins/list")
    async def list_plugins(request):
        services = request.app["services"]
        metadata = services.get("metadata")
        plugins = metadata.plugin_manager.list_plugins()
        return web.json_response({"ok": True, "data": plugins})

    @routes.post("/mjr/am/plugins/{name}/enable")
    async def enable_plugin(request):
        name = request.match_info["name"]
        services = request.app["services"]
        metadata = services.get("metadata")
        success = metadata.plugin_manager.enable_plugin(name)
        return web.json_response({"ok": success})

    @routes.post("/mjr/am/plugins/reload")
    async def reload_plugins(request):
        services = request.app["services"]
        metadata = services.get("metadata")
        count = await metadata.plugin_manager.reload()
        return web.json_response({"ok": True, "data": {"reloaded": count}})

Step 3: Register Routes

# mjr_am_backend/routes/registry.py

from .handlers.plugins import register_plugin_routes

def register_all_routes():
    # ... existing route registrations
    register_plugin_routes(routes)

---

🧪 Testing Strategy

Unit Tests

# tests/plugins/test_plugin_loader.py

class TestPluginLoader:
    def test_discover_plugins(self, tmp_path):
        loader = PluginLoader([tmp_path])
        count = loader.discover_plugins()
        assert count > 0

    def test_get_extractor_by_priority(self, tmp_path):
        loader = PluginLoader([tmp_path], auto_discover=False)
        loader.register_extractor(HighPriorityExtractor())
        loader.register_extractor(LowPriorityExtractor())

        extractor = loader.get_extractor("test.png")
        assert extractor.priority == 100  # Highest priority

Integration Tests

# tests/plugins/test_plugin_integration.py

class TestPluginIntegration:
    @pytest.mark.asyncio
    async def test_plugin_extraction(self, metadata_service):
        result = await metadata_service.extract_metadata("test.png", "image")
        assert result.get("success") is True

---

📈 Performance Metrics

Plugin Loading

Extraction Overhead

---

🎯 Success Criteria

---

📝 Next Steps

Immediate (Required for Functionality)

1. Modify MetadataService to use PluginManager
2. Add API routes for plugin management
3. Register routes in registry.py
4. Update deps.py to initialize plugin system

Short-Term (Enhancements)

1. Write unit tests for all plugin modules
2. Create frontend UI for plugin management
3. Add more example plugins (rgthree, ControlNet, etc.)
4. Document plugin API in main README

Long-Term (Future)

1. Plugin marketplace - Share plugins via PyPI
2. Plugin versioning - Automatic updates
3. Sandboxed execution - Better isolation
4. Performance profiling - Identify bottlenecks

---

🔗 Related Documents

• docs/PLUGIN_SYSTEM_DESIGN.md - Full architecture design
• docs/PLUGIN_QUICK_REFERENCE.md - Quick reference guide
• plugins/README.md - Plugin installation guide
• plugins/examples/ - Example plugins

---

📦 Distribution

Plugin Package Structure

majoor-my-plugin/
├── setup.py
├── README.md
└── my_plugin/
    ├── __init__.py
    └── extractor.py

# Installation
pip install majoor-my-plugin

PyPI Publishing

# setup.py
from setuptools import setup

setup(
    name="majoor-wanvideo-extractor",
    version="1.0.0",
    py_modules=["wanvideo_extractor"],
    entry_points={
        "majoor.plugins": [
            "wanvideo = wanvideo_extractor:WanVideoExtractor",
        ]
    },
)

---

Implementation Status: ✅ Core system complete, ready for integration

Estimated Integration Time: 2-4 hours

Risk Level: Low (isolated module, backward compatible)

Majoor Assets Manager - Privacy & Offline Guide

Version: 2.4.5 Last Updated: April 7, 2026

Overview

This page explains what Majoor Assets Manager processes locally, what can require network access, what the visible tokens are used for, and what "offline" means in practice.

Short Answer

• AI inference is intended to run locally on your machine.
• Images and prompts are not uploaded to a hosted cloud inference API for semantic search, captions, similarity, or prompt alignment.
• Internet access is mainly required for the initial HuggingFace model download.
• Once the required models are cached locally, AI features can work offline.
• No usage telemetry is intentionally sent to the developer.

What Stays Local

After models are available locally, these features run inside your local ComfyUI / Majoor process:

• semantic search
• find similar
• prompt alignment
• caption generation
• auto-tagging

This means Majoor does not rely on a hosted remote AI inference backend for those features.

What Uses The Network

Model download

AI features may download models from HuggingFace on first use. Those model files are then cached locally.

Typical cached model location:

~/.cache/huggingface/hub/

Optional HuggingFace token

The HuggingFace token is optional and only affects HuggingFace Hub access:

• better download reliability
• better Hub rate limits
• access to model download endpoints when needed

It is not a hosted AI inference key.

Remote access security

The Majoor API token is unrelated to HuggingFace. It protects remote write access to the local Majoor backend when ComfyUI is exposed on LAN, behind a reverse proxy, or through a tunnel.

It is not used to send prompts or images to an external AI service.

Token Clarification

Majoor exposes two token concepts that are easy to confuse:

HuggingFace Token

• optional
• used for model downloads from HuggingFace Hub
• improves download access and rate limits
• not used as a cloud inference token

Majoor API Token

• used for securing remote write operations
• applies to the local Majoor backend
• relevant when ComfyUI is reachable remotely
• not used for AI inference uploads

Offline Use

What works offline

AI features can work offline after the required models already exist in the local HuggingFace cache.

Non-AI Majoor features do not depend on HuggingFace model downloads.

What does not work offline on first use

If the model files are not already cached locally, first-time AI bootstrap requires network access to download them.

Important Nuance

The privacy statement here is specifically about:

• where inference runs
• whether prompts or images are uploaded for AI processing

That is different from saying there is zero upstream trust surface.

Model loading still depends on local HuggingFace / Transformers packages and downloaded model files. Some compatibility loaders may rely on upstream model packaging behavior. So the correct claim is:

• local inference, no hosted cloud upload of prompts/images for AI processing

not:

• zero external code or zero trust surface

Recommended Wording For Users

You can summarize Majoor's behavior like this:

AI features run locally on the user's machine. Prompts and images are not sent to a hosted cloud inference service for semantic search, similarity, captions, or alignment. Internet access is mainly needed only for the initial HuggingFace model download, and once models are cached locally the AI features can be used offline.

Related Documents

• AI_FEATURES.md
• SECURITY_ENV_VARS.md
• SETTINGS_CONFIGURATION.md

Majoor Assets Manager - Ratings, Tags & Collections Guide

Version: 2.4.5 Last Updated: April 5, 2026

Overview

The Majoor Assets Manager provides powerful organizational tools including ratings, tags, and collections to help you manage and organize your generated assets. This guide covers all features related to asset organization and categorization.

Recent highlights: Improved bulk operations, better Windows Explorer rating sync, and collection performance optimizations.

Rating System

Understanding Ratings

The rating system allows you to assign star ratings from 0 to 5 stars to your assets:

• 0 Stars: Poor quality or unusable
• 1 Star: Below average quality
• 2 Stars: Average quality
• 3 Stars: Good quality
• 4 Stars: Very good quality
• 5 Stars: Excellent quality

Setting Ratings

Via Context Menu

1. Right-click on an asset card
2. Select "Rate" from the context menu
3. Choose the desired star rating (0-5)
4. The rating is saved immediately

Via Keyboard Shortcuts

1. Select an asset card
2. Press the corresponding number key (0-5)
3. The rating is applied instantly

Via Rating Editor

1. Click on the rating stars directly on the asset card
2. Select the desired number of stars
3. The rating is saved automatically

Rating Features

Bulk Rating

• Select multiple assets using Ctrl/Cmd+click or Shift+click
• Apply the same rating to all selected assets
• Right-click and choose "Rate" to apply to all selections

Rating Filters

• Filter assets by minimum rating threshold
• Show only assets rated 3 stars or higher
• Quickly find your best results using rating filters

Rating Persistence

• Ratings are stored in the SQLite index database
• Ratings persist between ComfyUI sessions
• Ratings can be synchronized to file metadata (when external tools available)

Rating Synchronization

When ExifTool is available, ratings can be synced to file metadata:

• Ratings stored in file metadata for portability
• Maintains ratings when files are moved/copied
• Compatible with other applications that read ratings
• Enabled/disabled via settings

Windows rating mapping (why 99?)

When sync is enabled, the manager writes both star ratings (0–5) and Windows-style percent fields (RatingPercent / Microsoft:SharedUserRating) for best Explorer compatibility.

• 0★ → 0
• 1★ → 1
• 2★ → 25
• 3★ → 50
• 4★ → 75
• 5★ → 99 (many Windows handlers treat 99 as “max”)

Tagging System

Understanding Tags

Tags are customizable keywords that help categorize and organize your assets:

• Free-form text labels (e.g., "character", "landscape", "fantasy")
• Multiple tags per asset
• Hierarchical tagging support (e.g., "style:anime", "color:warm")
• Searchable across all assets

Adding Tags

Via Context Menu

1. Right-click on an asset card
2. Select "Edit Tags" from the context menu
3. Type tags separated by commas or spaces
4. Press Enter to save

Via Tags Editor

1. Click on an asset to select it
2. Open the details sidebar (press 'D')
3. Find the tags section
4. Add or remove tags as needed

Bulk Tagging

1. Select multiple assets
2. Right-click and choose "Edit Tags"
3. Add tags that apply to all selected assets
4. Tags are applied to all selected items

Managing Tags

Tag Suggestions

• System suggests previously used tags
• Intelligent autocomplete for faster tagging
• Recently used tags appear at the top of suggestions

Tag Validation

• Prevents duplicate tags on the same asset
• Validates tag format and content
• Sanitizes special characters when needed

Tag Search

• Search for assets by specific tags
• Combine tag searches with other filters
• Use partial tag names for broader results

Tag Features

Tag Hierarchy

• Use colons to create hierarchical tags: "subject:person:face"
• Organize tags in logical groups
• Facilitate more granular categorization

Tag Colors

• Visual indication of different tag types
• Customizable tag appearance
• Consistent color coding across the interface

Tag Statistics

• View tag frequency across your collection
• Identify most commonly used tags
• Analyze your tagging patterns

Tag Synchronization

When ExifTool is available, tags can be synced to file metadata:

• Tags stored in file metadata for portability
• Maintains tags when files are moved/copied
• Compatible with other applications that read tags
• Enabled/disabled via settings

Collections System

Understanding Collections

Collections are user-created groups of assets that can span multiple directories:

• Named groups of related assets
• Can include assets from different scopes (Outputs, Inputs, Custom)
• Persistent storage in JSON format
• Shareable between users

Creating Collections

From Selected Assets

1. Select one or more assets
2. Right-click and choose "Add to Collection"
3. Select an existing collection or create a new one
4. Name your new collection appropriately
5. Assets are added to the collection

From Search Results

1. Apply search and filters to find desired assets
2. Select all results (Ctrl+A or Cmd+A)
3. Right-click and choose "Add to Collection"
4. Create a new collection for the filtered results

Empty Collections

1. Right-click in the Collections tab
2. Choose "Create New Collection"
3. Name your collection
4. Add assets later as needed

Managing Collections

Collection Operations

• Rename: Change collection name via context menu
• Delete: Remove entire collection (doesn't delete assets)
• Clear: Remove all items from collection (doesn't delete assets)
• Export: Save collection as JSON file for sharing
• Import: Load collection from JSON file

Item Management

• Add Items: Add assets to existing collections
• Remove Items: Remove specific assets from collections
• Bulk Operations: Add/remove multiple items at once
• Duplicate Prevention: Automatic detection of duplicates

Collection Features

Smart Collections

• Dynamic collections based on criteria
• Automatically updated as new assets match criteria
• Based on tags, ratings, date ranges, or other attributes

Nested Collections

• Collections within collections (hierarchical)
• Organize large collections into subcategories
• Flexible organization structures

Collection Sharing

• Export collections as JSON files
• Import collections from other users
• Share curated sets of assets
• Collaborative collection building

Collection Limits

• Maximum 50,000 items per collection (configurable)
• Performance optimization for large collections
• Warning when approaching limits
• Suggestions for splitting large collections

Collection Views

Grid View

• Thumbnail display of collection contents
• Visual browsing of assets
• Consistent with main interface design

List View

• Detailed information display
• Sortable columns (name, date, size, rating)
• More information per asset

Compact View

• Dense layout for many items
• Efficient space utilization
• Quick scanning of large collections

Integration with Other Features

Search Integration

• Search within specific collections
• Cross-collection search capability
• Filter search results by collection membership
• Search for assets across all collections

Filtering Integration

• Filter by collection membership
• Combine collection filters with other filters
• Show only assets from specific collections
• Exclude assets from certain collections

Viewer Integration

• View collection context in viewer
• Navigate between collection items
• Show collection information in metadata panel
• Maintain collection context during comparisons

Rating and Tag Integration

• Apply ratings/tags to entire collections
• Filter collections by ratings/tags
• Bulk operations on collection contents
• Maintain rating/tag statistics per collection

Best Practices

Rating Best Practices

• Establish consistent rating criteria
• Use ratings consistently across similar assets
• Regularly review and adjust ratings as needed
• Use rating filters to quickly find quality assets

Tagging Best Practices

• Develop a consistent tagging vocabulary
• Use specific but not overly granular tags
• Maintain tag hierarchy for organization
• Regularly review and consolidate similar tags
• Use tags that will be meaningful later

Collection Best Practices

• Create collections based on clear criteria
• Use descriptive names for collections
• Regularly clean up unused collections
• Split large collections into more manageable groups
• Share valuable collections with others

Performance Considerations

Large Collections

• Collections with many items may take longer to load
• Interface remains responsive during loading
• Pagination helps manage large collections
• Consider splitting very large collections

Tag Performance

• Many tags per asset don't significantly impact performance
• Tag search remains fast regardless of quantity
• Regular cleanup of unused tags improves performance

Rating Performance

• Rating operations are nearly instantaneous
• Rating filters apply quickly to large datasets
• Bulk rating operations are optimized

Troubleshooting

Rating Issues

• Ratings not saving: Check database permissions
• Ratings not displaying: Refresh the view or rescan
• Sync issues: Verify ExifTool installation for file sync

Tagging Issues

• Tags not appearing: Check for typos or special characters
• Tag search not working: Ensure proper tag format
• Sync issues: Verify ExifTool installation for file sync

Collection Issues

• Collection not saving: Check write permissions to index directory
• Items not adding: Verify collection limits haven't been reached
• Collection not loading: Check JSON file integrity

Common Solutions

• Refresh Index: Use Ctrl/Cmd+S to rescan and refresh
• Clear Cache: Clear browser cache if interface seems stuck
• Check Logs: Look at ComfyUI console for detailed error messages
• Database Maintenance: Run optimization tools periodically

Advanced Features

Tag Expressions

• Complex tag queries using boolean logic
• Combine tags with AND/OR operations
• Parentheses for complex expressions
• Negation operators for exclusions

Rating Statistics

• View rating distributions across collections
• Track rating trends over time
• Identify most/least rated assets
• Generate reports on rating patterns

Collection Analytics

• View collection usage statistics
• Track most accessed collections
• Identify underutilized collections
• Analyze collection overlap and relationships

Automation Possibilities

• Script-based tag assignment
• Automated rating based on criteria
• Scheduled collection maintenance
• Integration with external tools

Security & Privacy

Local Storage

• Ratings and tags stored locally
• No external data transmission
• Full control over your organizational data
• Backup your index database regularly

File Metadata

• Optional synchronization to file metadata
• Controlled via settings
• Respects file permissions
• Preserves existing file metadata

---

Ratings, Tags & Collections Guide Version: 1.0 Last Updated: April 5, 2026