TopoViewer Studio

Support status: Beta Preview

This example keeps one portable bundle intact while changing the surface around it. The graph below is the documentation consumer. The same three source files are also the Studio import fixture and the Grafana consumer contract fixture.

Studio portable bundle

Try The Authoring Loop

Start Studio from the repository:

npm run studio:dev

In a browser that supports directory selection, open Project menu, choose Open folder, and select:

packages/topoviewer/content/examples/integration/studio-portable-bundle

Studio opens one YAML-first workbench: project source on the left, the selected YAML document in one shared editor, and the real TopoViewer preview beside it. Use Source, Split, and Preview to change presentation without changing the project. Split defaults to one-quarter source and three-quarters preview.

Open Object drawer under Authoring to place an object. Selecting an object opens preview-local Properties for its topology and appearance. Clicking empty preview opens canvas, grid, interaction, and layer settings. Pinning Mapper keeps telemetry authoring open while you inspect topology objects.

Select edge-a, change its Visible label in Properties, then select topology.yaml in project source to inspect the committed source and undo the change. Open Mapper Visual and paste a sample:

{
  "metric": "topoviewer_link_up",
  "source_id": "studio-portable-consumer",
  "link_id": "edge-a-core-b",
  "up": 0
}

Coverage should resolve the sample to edge-a-core-b and classify the down state. The topology ID and link ID do not change when runtime state changes.

Use Appearance in the header to choose System, Light, or Dark. System follows the operating system. Theme-owned canvas and grid colors follow that choice; explicit project colors remain unchanged.

Use archive import when folder access is unavailable

Browser folder access is not available everywhere. Create a Studio project and use the shared source workspace for topology, stylesheet, and optional mapper YAML. Export a .tvstudio archive after validation so the complete project can move as one file.

Publish The Documentation

This page is authored once in the canonical docs tree. npm run sync:docs projects it into both MkDocs and Zensical. The live viewport references the same example files rather than copying YAML into each documentation page.

Inspect the canonical mapper

version: 1
identity:
  sourceId: studio-portable-consumer
  sourceIdLabel: source_id
rules:
  - id: link-health
    metric: topoviewer_link_up
    select: link
    join: link_id
    value: up
    states:
      down: "==0"
    style:
      down:
        lineColor: "#d32f2f"

Package It For Grafana

In Studio, open Export project > Grafana. The readiness check confirms that mapper.yaml is present and valid before Export Grafana bundle becomes the production action. Studio then emits the mounted-bundle layout:

studio-portable-consumer/
  studio-portable-consumer.topo.tv.yaml
  studio-portable-consumer.style.tv.yaml
  studio-portable-consumer.mapper.tv.yaml
  manifest.json

Grafana receives runtime data frames and applies mapper overlays, but it does not own a different topology. Tests compile this canonical bundle through both the core renderer and the Grafana runtime model to detect semantic drift.

Reuse The Pattern

Keep one directory as the canonical bundle owner. Make authoring tools read and write those files, make docs embed them, and make operational packaging rename or wrap them without changing graph identity. Add a source-specific converter before the bundle when inventory comes from Kubernetes, NetBox, Infrahub, or an internal API; do not put source normalization inside each render surface.