Put a device in your own page.

Start here

A compiled device is one SVG per face (<device>.<config>.<view>.svg) plus devices.json, components.json and a <device>.configs.json and a <device>.source.json per device. The kit, @portrayal/kit, is plain ES modules with no build step; three.js is needed only for 3D. A face that several configurations draw identically is written once, so find a configuration's face with faceFile(index, config, view) from @portrayal/kit/dist rather than building its name; each device's default configuration is also at <device>.<view>.svg. The recipes below use the UfiSpace S9600-72XC.

The drawing is the API

No kit at all: fetch a face, insert it, and address its parts by data-path. A lamp is lit by a state class the drawing already styles; a click tells you which part it hit.

Color it from your data

A port is an element like any other, so your monitoring can paint it. Here the numbers are a table in the file; in a dashboard they are whatever your telemetry returns.

Read the device from the drawing

Each device publishes its source manifest once, as <device>.source.json: the device, its chassis in millimeters, its configurations. Every face names that file by its SHA-256 in <metadata>, so a drawing can be checked against the source it was drawn from. And devices.json lists everything in the library.

Seat an optic or a cable end

A cage is empty until you say what's in it. Name the part for the cage, and for an optic its two LC bores; the kit draws each part's own artwork into the face and refuses anything the cage doesn't accept.

In 3D

The same files, as a model you can turn over. The viewer takes the same paths and lamp states as the drawing (setStates), the same text on parts (setFields), and exports GLB and USDZ (download). It needs three.js; the page's import map says where that lives.

Annotate and export

Describe what to mark, not how to draw it: a document of selectors, colors, lamp states and labels. The same document previews on the page, exports as an SVG you can drop into Word (toSvg), or as a PNG or GIF (toPng, toGif), and fits in a share URL (encode).

The Explorer shell

If you want the whole explorer rather than parts of it, mount the shell. It styles the page it lands in, so it runs here in a frame of its own. The Explorer is the full example, with 3D.

Getting the files

Two things: the kit's modules, and the compiled files they read. Today you copy both - the kit is a dozen plain ES modules with no build step, and the compiled files are static - and serve them beside your page. Point an import map at the kit, and at three.js if you use 3D:

<script type="importmap">
{ "imports": {
    "@portrayal/kit/dist": "/vendor/portrayal-kit/dist.js",
    "@portrayal/kit/swap": "/vendor/portrayal-kit/swap.js",
    "@portrayal/kit/viewer3d": "/vendor/portrayal-kit/viewer3d.js",
    "@portrayal/kit/marks": "/vendor/portrayal-kit/marks.js",
    "@portrayal/kit/shell": "/vendor/portrayal-kit/shell.js",
    "three": "/vendor/three/three.module.js",
    "three/addons/": "/vendor/three/addons/"
} }
</script>

and set DIST in each recipe to wherever the compiled files are. The 2D recipes don't need three.js at all. List each kit module you use, as above; once the kit is on npm, a bundler or an import map generator resolves @portrayal/kit/viewer3d through the package's exports.

How the kit and the compiled files are distributed is being settled: @portrayal/kit on npm, and a registry for the compiled files (roc-ops/Portrayal #526, #527, #528). This section will change when those land.