3D Asset Intelligence

3D Asset Intelligence is a production-grade VS Code extension designed for technical artists, 3D graphics engineers, and platform developers. It provides deterministic, offline-first analysis of GLB/glTF 3D assets, evaluating them against professional performance budgets (Web, Mobile, AR, VR).

Features (V1)

• Deterministic Binary Parsing: Safely extracts geometry, materials, and textures without loading massive binaries into RAM, preventing VS Code from crashing.
• Asset Health Scoring: Automatically scores assets out of 100 based on their performance topology.
• Platform Readiness Profiles: Compares exact triangle counts and estimated texture VRAM against strict Web and Mobile budgets.
• Actionable Diagnostics: Generates deterministic Findings (CRITICAL, HIGH, MEDIUM, LOW) instructing artists on how to fix issues (e.g., "Reduce triangle count below 500k using decimation").
• Local-First & Secure: Analyzes all assets entirely locally on your machine. The extension implements an aggressive Content Security Policy (CSP) blocking external telemetry, ensuring enterprise assets remain private.

Architecture Highlights

1. Off-Thread Extraction Engine: Uses Node.js Worker Threads (WorkerManager) to dissect the GLB binary.
2. React Webview Dashboard: Presents a dynamic, reactive UX over the VS Code IPC boundary.
3. RuleEngine & ScoringEngine: Pluggable architectures allowing for future custom enterprise budgets.

Quick Start

1. Install dependencies: npm install
2. Compile the extension: npm run compile
3. Press F5 in VS Code to launch the Extension Development Host.
4. Right-click any .glb file in the Explorer and select "3D Asset Intelligence: Analyze Asset".

Development Commands

• npm run watch: Run the TypeScript compiler in watch mode.
• npm run build:webview: Bundle the React dashboard using Vite.
• npm run test:unit: Run the vitest test suite.

Security Overview

The DashboardPanel is fortified against malicious assets:

• connect-src 'none' prevents network exfiltration.
• Dynamic nonces are used for script injection.
• Worker threads gracefully intercept malformed binary chunk boundaries without crashing.

1. Core Architectural Principles

• Local-First & Privacy Preserving: Assets are analyzed entirely locally. No massive 3D files are uploaded to the cloud unless explicit AI assistance is triggered for textual explanations.
• Memory-Aware Progressive Analysis: DO NOT load a multi-gigabyte 3D asset into the UI thread. The architecture relies on binary header inspection, array buffer streaming, and off-thread Node.js worker processing to prevent memory bloat and UI freezing.
• Deterministic Metrics: Scoring out of 100 is strictly formula-based using measured metrics (vertex counts, texture dimensions) against defined platform rules. AI is never used to invent or guess technical facts.

2. High-Level Architecture Flow

VS Code Extension Host (extension.ts)
 │
 ├──> 1. Format Detection (GlbAdapter reads first 12 magic bytes)
 │
 ├──> 2. WorkerManager (Orchestrates bounded concurrency)
 │     │
 │     └──> analysis.worker.ts (Off-thread binary chunk parsing)
 │           ├── GeometryAnalyzer (Triangles, Vertices, LODs)
 │           ├── TextureAnalyzer (VRAM estimation, dimensions)
 │           ├── MaterialAnalyzer (PBR, transparent passes)
 │           └── StructureAnalyzer (Hierarchy depth)
 │
 ├──> 3. AnalysisCache (Caches by SHA-256 stream hash + Engine Version)
 │
 ├──> 4. RuleEngine & ScoringEngine (Calculates Web/Mobile/AR/VR readiness)
 │
 └──> 5. React Webview Dashboard (DashboardPanel.ts)
       (Renders strictly via typed ExtensionMessage protocol)

3. Project Structure (Monorepo)

3d-asset-intelligence/
├── src/
│   ├── extension/          # VS Code lifecycle, commands, Webview host
│   ├── core/               
│   │   ├── analyzer/       # Binary chunk parsers (Geometry, Texture, etc.)
│   │   ├── rules/          # Rule Engine and Platform Profiles (Web, VR, etc.)
│   │   ├── scoring/        # Deterministic Score calculation
│   │   ├── optimization/   # Non-destructive optimization pipelines
│   │   ├── reporting/      # JSON/HTML report generators
│   │   └── parser/         # ProjectScanner for workspace folder aggregation
│   ├── workers/            # Job queues, WorkerManager, and worker_threads
│   ├── formats/            # Adapters (AssetFormatAdapter, GlbAdapter)
│   ├── storage/cache/      # AnalysisCache (SHA-256 persistent cache)
│   ├── ai/                 # AIProvider interface (Strict text-only explanations)
│   ├── shared/types/       # Data contracts (NormalizedAssetModel, Messages)
│   └── utils/              # Stream hashing, math utilities
├── webview/                # React + Vite application (VS Code UI)
│   └── src/
│       ├── components/     # MetricCard, ScoreRing, FindingCard
│       └── App.tsx         # Dashboard layout and message listeners
├── tests/                  # Unit and Integration tests
└── package.json            # Extension manifest and scripts

4. The Normalized Asset Model

The system translates format-specific data (like GLB JSON chunks) into a strictly typed NormalizedAssetModel used universally across the UI and AI components.

export interface NormalizedAssetModel {
  metadata: {
    id: string; // SHA-256 hash
    format: string;
    fileSize: number;
    // ...
  };
  geometry?: {
    meshCount: number;
    triangleCount: number;
    estimatedGpuMemoryBytes: number;
  };
  texture?: {
    textureCount: number;
    estimatedMemoryBytes: number;
  };
  material?: {
    pbrMaterialCount: number;
    transparentMaterialCount: number;
  };
  animation?: {
    animationCount: number;
    totalKeyframes: number;
  };
}

5. Security & Stability Mechanisms

• Webview CSP: The React dashboard uses a dynamically generated nonce for scripts and strictly blocks remote code execution.
• Worker Cancellation: The WorkerManager supports cancelJob(), which immediately posts a CANCEL message to the worker thread and triggers worker.terminate() to prevent zombie processes.
• Non-Destructive Optimization: The OptimizationEngine is hard-coded to require a new outputDir. It will never overwrite the source asset.

6. Technical Stack

• Extension Runtime: Node.js, vscode API, worker_threads
• UI: React 18, Vite, standard CSS (Dark mode optimized)
• Language: Strict TypeScript (ES2022, NodeNext)
• Testing: Vitest
• Linting: ESLint flat config + Prettier

7. Development & Build Commands

# Install root extension dependencies
npm install

# Install React Webview dependencies
cd webview && npm install

# Build the Webview specifically (Required before extension launch)
npm run build:webview

# Compile the entire extension
npm run compile

# Run tests
npm run test:unit

To run in VS Code:

1. Open the project folder in VS Code.
2. Press F5 to launch the Extension Development Host.
3. Use the command palette: 3D Asset Intelligence: Analyze Asset.