# Plugin Specification

## Goal

The plugin system should allow additional rack components to be imported without changing application code.

Plugins should be data packages, not executable extensions.

## Principles

- no arbitrary code execution
- manifest-based validation
- stable schema versioning
- internal conversion of optional CAD-derived assets

## Package structure

Example:

```text
vendor-pack-1/
  manifest.json
  components/
    switch-24p.json
    patchpanel-24p.json
  assets/
    front/
      switch-24p.svg
      patchpanel-24p.svg
    preview3d/
      switch-24p.gltf
```

## Manifest example

```json
{
  "manifestVersion": 1,
  "name": "Example Network Pack",
  "vendor": "Example Vendor",
  "version": "1.0.0",
  "components": [
    "components/switch-24p.json",
    "components/patchpanel-24p.json"
  ]
}
```

## Component definition example

```json
{
  "name": "24-Port Patch Panel",
  "manufacturer": "Example Vendor",
  "partNumber": "PP-24-1U",
  "category": "patch_panel",
  "rackStandard": "19_inch",
  "heightU": 1,
  "depthMm": 95,
  "weightKg": 1.2,
  "priceNet": 79.0,
  "currency": "EUR",
  "assets": {
    "frontSvg": "assets/front/patchpanel-24p.svg"
  },
  "ports": [
    {
      "name": "Port 1",
      "side": "front",
      "offsetXmm": 18,
      "offsetYmm": 10,
      "offsetZmm": 0,
      "portType": "rj45"
    }
  ]
}
```

## Supported file formats

### V1 mandatory

- `JSON` for manifest and component metadata
- `SVG` for 2D visuals

### V1 optional

- `glTF` for future 3D preview assets

### Later import formats

These should be handled through an import pipeline, not as runtime-native editor formats:

- `DXF`
- `STEP`
- `OBJ`

## Validation rules

- schema version must be supported
- required metadata fields must exist
- asset references must resolve inside the package
- all dimensions must be plausible and positive
- category values must match allowed enums
- unsupported formats are rejected or ignored

## Security model

Plugins must never contain executable JavaScript for the editor.

Allowed plugin content:

- metadata
- images
- vector graphics
- optional validated model assets

Rejected:

- scripts
- external network callbacks
- embedded active content

## Import workflow

1. upload package
2. unpack in isolated temporary storage
3. validate manifest
4. validate component schema
5. validate assets
6. register catalog entries
7. make components available to selected users or globally

## Versioning strategy

- application schema versioning is independent from plugin pack version
- manifest schema must be explicitly versioned
- deprecated fields should have a migration path where possible