` wrappers for interactive controls. ### Color Contrast The dark theme (`--tds-bg: #1d1f27`) with light text (`--tds-text: #e6e8e9`) maintains readable contrast ratios. Accent colors are used for emphasis rather than conveying essential information alone. ### Node ID Display The `I` keyboard shortcut (or `toggleNodeIds()` method) overlays element IDs on the diagram in red text, useful for debugging and understanding the topology structure without needing to inspect the source code. --- ## 21. Complete Example: Building a Topology from Scratch Here's a full example demonstrating all major features: ```javascript const topo = new TopologyDesigner({ title: 'Data Center Network', subtitle: 'Core · Distribution · Access', viewBox: '0 0 900 600', phaseMs: 500, }); // ── NODES ── // Core layer topo.node('CORE1', { type: 'router', x: 350, y: 100, label: 'Core-1', color: '#01a982' }); topo.node('CORE2', { type: 'router', x: 550, y: 100, label: 'Core-2', color: '#01a982' }); // Distribution topo.node('FW1', { type: 'firewall', x: 250, y: 250, label: 'Firewall' }); topo.node('SW1', { type: 'switch', x: 450, y: 250 }); topo.node('SW2', { type: 'switch', x: 650, y: 250 }); // Access topo.node('SRV1', { type: 'server', x: 350, y: 400, label: 'App Server', color: '#01a982' }); topo.node('DB1', { type: 'database', x: 550, y: 400, label: 'Database' }); topo.node('HOST1', { type: 'host', x: 150, y: 400, label: 'Admin' }); // External topo.node('INET', { type: 'cloud', x: 450, y: 30, label: 'Internet', color: '#b1b9be' }); // ── LINKS ── topo.link('inet-core1', { type: 'line', from: 'INET', to: 'CORE1', color: '#b1b9be' }); topo.link('inet-core2', { type: 'line', from: 'INET', to: 'CORE2', color: '#b1b9be' }); topo.link('core-core', { type: 'tunnel', from: 'CORE1', to: 'CORE2', color: '#01a982', label: 'iBGP', dots: true }); topo.link('core1-fw', { type: 'line', from: 'CORE1', to: 'FW1', color: '#fc6161' }); topo.link('core1-sw1', { type: 'line', from: 'CORE1', to: 'SW1', color: '#01a982' }); topo.link('core2-sw2', { type: 'line', from: 'CORE2', to: 'SW2', color: '#01a982' }); topo.link('sw1-srv', { type: 'line', from: 'SW1', to: 'SRV1', color: '#01a982' }); topo.link('sw2-db', { type: 'line', from: 'SW2', to: 'DB1', color: '#deb146' }); topo.link('fw-host', { type: 'line', from: 'FW1', to: 'HOST1', color: '#fc6161' }); // ── ACTS & STEPS ── topo.act('a1', { label: 'Act 1 · Core', color: '#01a982', intro: ['The backbone of the data center.'] }); topo.act('a2', { label: 'Act 2 · Services', color: '#deb146', intro: ['Application and data tiers.'] }); topo.act('a3', { label: 'Act 3 · Access', color: '#fc6161', intro: ['Security and user access.'] }); // Act 1 steps topo.addStep('core', { act: 'a1', name: 'Core Routers', goal: 'Deploy redundant core routing.', focus: ['CORE1', 'CORE2'], phases: [ { show: ['INET'], diff: 'Internet cloud' }, { show: ['CORE1', 'inet-core1'], diff: 'Core-1 with uplink' }, { show: ['CORE2', 'inet-core2'], diff: 'Core-2 with uplink' }, { show: ['core-core'], diff: 'iBGP peering tunnel' }, ], }); // Act 2 steps topo.addStep('distro', { act: 'a2', name: 'Distribution Layer', goal: 'Switches connect core to services.', focus: ['SW1', 'SW2', 'SRV1', 'DB1'], phases: [ { show: ['SW1', 'core1-sw1'], diff: 'Switch 1 connects to Core-1' }, { show: ['SW2', 'core2-sw2'], diff: 'Switch 2 connects to Core-2' }, { show: ['SRV1', 'sw1-srv'], diff: 'App server behind Switch 1' }, { show: ['DB1', 'sw2-db'], diff: 'Database behind Switch 2' }, ], }); // Act 3 steps topo.addStep('security', { act: 'a3', name: 'Firewall & Access', goal: 'Secure admin access through firewall.', focus: ['FW1', 'HOST1'], phases: [ { show: ['FW1', 'core1-fw'], diff: 'Firewall deployed' }, { show: ['HOST1', 'fw-host'], diff: 'Admin workstation via firewall' }, ], }); // ── GLOSSARY ── topo.glossary([ { t: 'iBGP', d: 'Internal BGP: routing protocol between core routers in the same AS.' }, { t: 'Distribution', d: 'Network layer providing policy-based connectivity between access and core.' }, ]); // ── MOUNT ── topo.mount('app'); ``` --- ## 22. Implementing Link Draw Animations This section explains exactly how to replicate the link-drawing-from-one-end-to-the-other animation in your own custom code. ### The Core Technique: stroke-dashoffset Animation The trick relies on SVG's `stroke-dasharray` and `stroke-dashoffset` properties: 1. Set `stroke-dasharray="2000"` — this creates a single dash of 2000px followed by a 2000px gap 2. Set `stroke-dashoffset="0"` on the element (the final state) 3. Animate from `stroke-dashoffset: 2000` to `0` — as the offset decreases, the dash slides into view, creating a "drawing" effect ### Step-by-Step Implementation #### 1. Basic Drawing Line ```html ``` #### 2. Drawing with Delay (for sequencing) ```html ``` The `backwards` fill mode in the animation ensures the element stays invisible during the delay period. #### 3. Drawing a Curved Path The same technique works with SVG `` elements: ```html ``` #### 4. Multi-Layer Drawing (Tunnel Effect) For richer visuals, layer multiple elements: ```html ``` #### 5. Using the Engine's Built-in Methods In custom render hooks, use the engine's link renderers directly: ```javascript onRender: (ctx) => { let svg = ''; // Draw a flow from point A to point B when phase 0 is active svg += ctx.renderFlow( 'myStep', // step ID 0, // phase number 'M100,200 C300,100 500,100 700,200', // SVG path '#05cc93', // color 'Data Flow', // label text 400, 140, // label position (x, y) ctx.dim('NODE1'), // opacity (based on focus) true // show animated dots ); // Draw a simple line in phase 1 svg += ctx.renderLine( 'myStep', 1, 100, 300, 700, 300, '#fc6161', ctx.dim('NODE2'), true // dashed ); return svg; } ``` #### 6. Controlling Draw Direction The line draws from `(x1,y1)` to `(x2,y2)`. To reverse the direction, swap the coordinates: ```javascript // Draws left-to-right { from: 'LEFT_NODE', to: 'RIGHT_NODE' } // Draws right-to-left (swap from/to) { from: 'RIGHT_NODE', to: 'LEFT_NODE' } ``` For paths, reverse the path string: ```javascript // Forward: draws from HOST to NAC const forward = `M${HOST.x},${HOST.y} L${NAC.x},${NAC.y}`; // Return: draws from NAC back to HOST const returnPath = `M${NAC.x},${NAC.y} L${HOST.x},${HOST.y}`; ``` --- ## 23. Plugin System The engine uses a formal plugin interface for node and link types. ### Registering Node Plugins ```javascript TopologyDesigner.registerNodeType('myDevice', { // Required: render function render(x, y, cfg) { return ``; }, // Optional: default configuration values defaults: { color: '#01a982', size: 40 }, // Optional: hit box for click detection hitBox(x, y, cfg) { return { x: x - 20, y: y - 20, width: 40, height: 40 }; }, // Optional: validation validate(cfg) { return cfg.size > 0; }, // Optional: metadata meta: { label: 'My Device', category: 'custom' }, // Optional: lifecycle hooks init(cfg) { /* called on registration */ }, destroy(cfg) { /* called on removal */ }, }); ``` ### Registering Link Plugins ```javascript TopologyDesigner.registerLinkType('myLink', { render(fromPt, toPt, cfg, ctx) { return ``; }, defaults: { color: '#01a982' }, meta: { label: 'My Link', category: 'custom' }, }); ``` ### Lifecycle Hooks The engine supports lifecycle hooks for observing render and step change events: ```javascript topo.on('beforeRender', (ctx) => { // Called before the SVG is rendered }); topo.on('afterRender', (ctx) => { // Called after the SVG is rendered }); topo.on('onStepChange', ({ prevStep, step, designer }) => { // Called when the current step changes }); ``` ### Querying Registered Types ```javascript // Get all registered node types (built-in + plugins) TopologyDesigner.getRegisteredNodeTypes(); // → ['ec', 'switch', 'switchEnterprise', 'cloud', 'host', 'connector', ...] // Get all registered link types (built-in + plugins) TopologyDesigner.getRegisteredLinkTypes(); // → ['line', 'tunnel', 'wireguard', 'flow', 'packet', 'blocked', 'wifi', 'poe', 'optical'] ``` --- ## 24. SVG Diffing & Incremental Rendering The engine uses a virtual-DOM-lite approach for efficient rendering: 1. **Dirty element tracking**: On each phase transition, `computeDirtyElements()` identifies which nodes and links need updating. 2. **Incremental render**: `incrementalRender()` only updates changed SVG elements rather than re-rendering the entire canvas. 3. **Single element render**: `renderSingleElement()` updates individual nodes or links in-place. This significantly improves performance for large topologies where only a few elements change per step. --- ## 25. Smart Link Routing Links automatically detect and route around obstructing nodes: 1. **AABB collision detection**: Each node's bounding box is checked against the straight-line path of each link. 2. **Auto-detour**: When a collision is detected, the link is rerouted using a quadratic Bezier curve that arcs around the obstructing node. 3. **Dynamic recalculation**: Routes update when nodes are moved or the topology changes. This prevents links from overlapping with nodes in dense topologies. --- ## 26. Choreography Smoothing The `setNodePositions()` API enables position keyframes across steps: ```javascript topo.setNodePositions('step2', { 'R1': { x: 300, y: 200 }, 'SW1': { x: 500, y: 300 }, }); ``` When advancing to a step with position keyframes, nodes animate smoothly to their new positions using cubic ease-in-out interpolation via `requestAnimationFrame`. This enables nodes to move during the narrative, creating dynamic topology animations. --- ## 27. Layout Engine Seven auto-layout algorithms are available: | Algorithm | Description | |-----------|-------------| | `force-directed` | Physics simulation with repulsion and spring forces for organic layouts | | `hierarchical` | Top-down layered layout following link direction | | `circular` | Nodes arranged in a circle | | `grid` | Regular grid arrangement | | `magnetic-north` | Type-aware force-directed layout that zones nodes by their role | | `spine-leaf` | Data-center optimized: high-degree spine nodes on top row, leaf nodes below | | `cluster` | Groups nodes by connected components; each cluster is laid out circularly | ```javascript // Via API topo.autoLayout('force-directed'); // Via modules (if loaded) const layout = new LayoutEngine(topo); layout.apply('hierarchical', { spacing: 100, animate: true }); ``` Layouts animate transitions when the `animate` option is enabled. ### Magnetic North Layout A type-aware force-directed algorithm that assigns vertical zones based on node type, producing layouts that reflect real-world network hierarchy (cloud at the top, hosts at the bottom). ```javascript const positions = LayoutEngine.magneticNorth(nodes, links, { width: 1050, height: 700, iterations: 200, padding: 60, repulsion: 5000, attraction: 0.005, damping: 0.92, minDistance: 80, magnetStrength: 0.3, }); // Returns a Map of { nodeId: { x, y } } ``` **Options:** | Option | Type | Default | Description | |--------|------|---------|-------------| | `width` | `number` | `1050` | Canvas width | | `height` | `number` | `700` | Canvas height | | `iterations` | `number` | `200` | Number of simulation iterations | | `padding` | `number` | `60` | Edge padding | | `repulsion` | `number` | `5000` | Repulsion force between nodes | | `attraction` | `number` | `0.005` | Attraction force along links | | `damping` | `number` | `0.92` | Velocity damping per iteration | | `minDistance` | `number` | `80` | Minimum distance between nodes | | `magnetStrength` | `number` | `0.3` | Strength of the vertical zone pull | **Zone mapping (vertical position as fraction of height):** | Zone | Node Types | Y Position | |------|------------|------------| | Top | `cloud` (0.12), `overlayCloud` (0.08), `saas` (0.18) | Near top of canvas | | Center | `router` (0.45), `firewall` (0.42), `switch` (0.48), `ec` (0.55) | Middle of canvas | | Bottom | `host` (0.82), `database` (0.78), `apps` (0.75) | Near bottom of canvas | Nodes are attracted toward their zone's Y position by `magnetStrength`, while standard repulsion and attraction forces handle horizontal spacing and link proximity. --- ## 28. Template System 7 built-in templates for common topologies: | Template | Description | |----------|-------------| | `hub-spoke` | Central hub with radial connections | | `3-tier` | Classic three-tier architecture (core/distribution/access) | | `mesh` | Full or partial mesh interconnection | | `star` | Star topology with central node | | `spine-leaf` | Data center spine-leaf fabric | | `sd-wan` | SD-WAN overlay architecture | | `firewall-dmz` | Firewall with DMZ zones | ```javascript topo.loadTemplate('spine-leaf'); ``` ### Diagram-as-Code Import topologies from a Mermaid-esque text format: ```javascript topo.importFromText(` R1[router] -- line --> SW1[switch] SW1 -- tunnel --> SW2[switch] SW2 -- line --> SRV1[server] `); ``` The editor includes a Diagram-as-Code modal with syntax reference and both import/export capabilities. --- ## 29. Theme Engine 5 built-in color presets plus custom palette generation: ```javascript // Apply a built-in theme topo.applyTheme('default-dark'); // Green accent, dark background topo.applyTheme('midnight'); // Subdued, cool tones topo.applyTheme('charcoal'); // High contrast topo.applyTheme('corporate'); // Professional blue topo.applyTheme('warm-dark'); // Orange/amber tones ``` Features: - **Brand color generation**: Generate a full palette from a single brand color - **WCAG contrast checking**: Validates that color combinations meet accessibility contrast ratios - **CSS export**: Export theme as CSS custom properties - **Runtime switching**: Change themes without re-rendering the topology --- ## 30. Animated GIF Export The editor can export the topology choreography as an animated GIF: 1. **Real choreography frames**: Creates a temporary `TopologyDesigner` per step, stepping through the actual choreography (step 0 → N) to capture genuinely different frames. 2. **Median-cut quantization**: Samples pixels across multiple frames to build an optimal 256-color palette. 3. **Floyd-Steinberg dithering**: Error diffusion at 40% strength for smooth gradients on dark backgrounds. 4. **Resolution**: 1200px wide for sharp output. 5. **Per-frame timing**: First frame holds 1.5s, last frame holds 3s, intermediate steps at 2.5s each. Access via **File > Export GIF** in the editor toolbar. --- ## 31. Temporal Digital Twin The system supports three temporal modes that transform the topology from a static diagram into a live operational view or historical incident replay. ### Temporal Modes | Mode | Description | |------|-------------| | `design` | Default mode. Planned/architectural view with no live data. | | `operational` | Live metrics mode. Nodes display real-time status, latency, jitter, and loss. | | `incident` | Historical replay mode. Used for post-mortem analysis of past incidents. | ### API ```javascript // Switch temporal mode topo.setTemporalMode('operational'); // Set live metrics on a single element topo.setElementState('R1', { status: 'degraded', latency: 45, // milliseconds jitter: 12, // milliseconds loss: 2.5, // percentage }); // Bulk-set state data for multiple elements topo.setStateData({ 'R1': { status: 'healthy', latency: 5, jitter: 1, loss: 0 }, 'FW1': { status: 'degraded', latency: 120, jitter: 30, loss: 1.2 }, 'SW1': { status: 'down', latency: 0, jitter: 0, loss: 100 }, }); ``` ### Constructor Options ```javascript new TopologyDesigner({ temporalMode: 'design', // Initial temporal mode onTemporalModeChange: (mode) => { // Callback on mode switch console.log('Switched to', mode); }, }); ``` ### Visual Effects by Status | Status | Visual Effect | |--------|--------------| | `healthy` | Green status dot | | `degraded` | Yellow pulsing ring + jitter SVG filter (displacement map) | | `down` | Red pulsing ring + desaturate and blur filter | | `breached` | Red noise displacement filter + red glow | ### Toolbar A temporal mode dropdown selector appears in the toolbar with three options: Design, Operational, and Incident. Switching modes triggers the `onTemporalModeChange` callback and re-renders the topology with the appropriate visual treatment. --- ## 32. Isometric Tilt Mode Pseudo-3D orthographic projection that gives topologies a cinematic SOC dashboard aesthetic. When enabled, the entire canvas tilts into an isometric perspective while text labels counter-rotate to stay readable. ### Enabling Isometric Tilt **Viewer** — Click the **Tilt** button in the toolbar. The button highlights green when active. **Editor** — Open the **View** menu and select **Isometric Tilt**, or press Shift+T. The menu item highlights when active. **Programmatic API:** ```javascript // Toggle isometric view (returns current boolean state) const isOn = topo.toggleIsometric(); // Toggle const isOn = topo.toggleIsometric(true); // Force enable const isOn = topo.toggleIsometric(false); // Force disable ``` ### Constructor Option ```javascript new TopologyDesigner({ isometricMode: false, // Start in isometric mode (default: false) }); ``` ### CSS Class The toggle adds the `tds-isometric` class to the canvas container and `tds-isometric-svg` to the SVG element: ```css /* Canvas tilt */ .tds-canvas.tds-isometric { transform: perspective(1200px) rotateX(45deg) rotateZ(-45deg); transform-origin: center center; transition: transform 0.8s cubic-bezier(.4, 0, .2, 1); } /* Subtle hover shift for interactivity */ .tds-canvas.tds-isometric:hover { transform: perspective(1200px) rotateX(42deg) rotateZ(-43deg); } /* Counter-rotate text labels so they remain readable */ .tds-isometric-svg text { transform: rotateZ(45deg) rotateX(-45deg); transform-origin: center; transform-box: fill-box; } ``` ### How It Works 1. A `perspective(1200px)` creates the 3D projection context. 2. `rotateX(45deg)` tilts the canvas backward (top recedes). 3. `rotateZ(-45deg)` rotates the plane to produce the classic isometric angle. 4. Text elements inside the SVG receive the inverse rotation (`rotateZ(45deg) rotateX(-45deg)`) so labels remain upright and legible. 5. On hover the angles ease slightly (`42deg` / `-43deg`) to provide subtle interactive feedback. 6. The transition uses a `cubic-bezier(.4, 0, .2, 1)` easing over 0.8 seconds for a smooth toggle animation. ### Limitations - **Drag precision** — In the Editor, node dragging coordinates are unaffected by the visual transform, so nodes move along the original (flat) axes rather than the projected axes. This can feel unintuitive while editing; disable tilt for precise positioning work. - **Hit testing** — Click targets remain in flat 2D space. Pointer coordinates are not inverse-projected, so elements may appear slightly offset from their click zones at extreme zoom levels. - **Print / export** — CSS 3D transforms are not captured by SVG-based export. Exported images will show the flat (non-tilted) view. - **Performance** — The 3D transform triggers GPU compositing. On low-powered devices with very large topologies, enabling tilt may reduce frame rates during pan/zoom. --- ## 33. Intelligence Layer Smart topology analysis with security validation and blast radius visualization. ### Path Validation Validate that a path between two nodes meets security rules: ```javascript const result = topo.validatePath('HOST1', 'SRV1', { requireTypes: ['firewall'], // Path must traverse a firewall node forbidDirect: true, // Direct connections are not allowed }); // result = { // valid: true|false, // path: ['HOST1', 'FW1', 'SW1', 'SRV1'], // Discovered path // violations: ['Direct connection without firewall'], // If invalid // } ``` ### Topology Validation Validate all links against security rules: ```javascript const violations = topo.validateTopology({ requireTypes: ['firewall'], }); // Returns array of violation objects // Shows red pulsing halos on violating elements ``` ### Security Mode ```javascript // Toggle security analysis mode topo.toggleSecurityMode(); // Toggle topo.toggleSecurityMode(true); // Force enable ``` In security mode, clicking a node activates blast radius visualization for that node. ### Blast Radius Visualize the set of nodes reachable from a given node within N hops via BFS traversal: ```javascript // Get the set of reachable node IDs within 2 hops const reachable = topo.getBlastRadius('FW1', 2); // Returns Set of node IDs // Set the blast radius center node (dims everything outside the radius) topo.setBlastRadiusNode('FW1'); // Clear blast radius visualization topo.setBlastRadiusNode(null); ``` ### Constructor Option ```javascript new TopologyDesigner({ blastRadiusHops: 2, // Default hop count for blast radius (default: 2) }); ``` ### Behavior - In security mode, clicking a node automatically calls `setBlastRadiusNode()` for that node - Elements outside the blast radius are dimmed - Path violations display with red warning icons and tooltip text - Topology validation shows red pulsing halos on elements that violate the rules ### Toolbar A "Security" button in the toolbar toggles security analysis mode. --- ## 34. Ghosting Engine Previous act elements desaturate and blur instead of vanishing, maintaining spatial context across act transitions. ### Constructor Option ```javascript new TopologyDesigner({ ghosting: true, // Enable ghosting (default: true) }); ``` ### Behavior When ghosting is enabled and the topology transitions between acts, elements from previous acts are not hidden. Instead, they automatically receive a ghost treatment: - **Desaturation**: Reduced to 15% saturation - **Blur**: Subtle 0.8px blur applied - **Opacity fade**: Reduced opacity based on act distance (elements from deeper in the past become more transparent, with a minimum opacity of 0.08) - **SVG filter**: Uses the `tds-ghost` SVG filter for the desaturation and blur effect This preserves the spatial layout context so viewers can still see where previous infrastructure was placed, while clearly distinguishing current-act elements from past ones. --- ## 35. Conditional Step Logic State variables and conditional phase evaluation for dynamic topologies. This is part of the Diagram-as-Code 2.0 feature set. > **See also:** [Flow Paths](#36-flow-paths), [Policy Markers](#37-policy-markers), and [Layer System](#38-layer-system) for additional overlay and grouping features. ### State Variables ```javascript // Set a state variable topo.setState('firewall.status', 'breached'); // Get a state variable value const status = topo.getState('firewall.status'); // → 'breached' ``` ### Conditional Phases Phases can include a `condition` property that is evaluated against the current state. If the condition is falsy, the phase is skipped. ```javascript topo.addStep('quarantine', { act: 'a2', name: 'Automated Response', goal: 'System reacts to breach detection.', focus: ['FW', 'tunnel-01'], phases: [ { show: ['tunnel-01'], condition: 'firewall.status == "breached"', actions: [ { changeLink: 'tunnel-01', toType: 'blocked', reason: 'Automated Quarantine' }, { changeNode: 'FW', cfg: { color: '#fc6161' } }, { setState: { 'quarantine.active': true } }, ], }, ], }); ``` ### Condition Syntax Conditions are evaluated against the topology state variables. Supported operators: | Operator | Example | Description | |----------|---------|-------------| | `==` | `'firewall.status == "breached"'` | Equality check | | `!=` | `'quarantine.active != true'` | Inequality check | | `>` | `'metrics.latency > 100'` | Greater than | | `<` | `'metrics.loss < 5'` | Less than | | *(none)* | `'quarantine.active'` | Truthy check | ### Phase Actions When a conditional phase evaluates to true, its `actions` array is executed in order: | Action | Description | |--------|-------------| | `{ changeLink: id, toType: type, reason?: string }` | Change a link's type (e.g., from `tunnel` to `blocked`) | | `{ changeNode: id, cfg: { ... } }` | Update a node's configuration (e.g., change color) | | `{ setState: { key: value, ... } }` | Set one or more state variables | --- ## 36. Flow Paths Flow paths are animated overlay paths that follow waypoints through the topology, visualizing data flows, traffic patterns, or service chains across multiple nodes. ### Registration ```javascript topo.flowPath(id, config) ``` | Parameter | Type | Description | |-----------|------|-------------| | `id` | `string` | Unique identifier (e.g. `'fp_1'`) | | `config.waypoints` | `string[]` | Ordered array of node/anchor IDs the path passes through | | `config.color` | `string` | Path color | | `config.animation` | `string` | Animation style: `'particles'` \| `'dashed'` \| `'pulse'` (default: `'particles'`) | | `config.speed` | `number` | Animation speed in seconds (default: 2) | | `config.direction` | `string` | `'forward'` \| `'reverse'` \| `'bidirectional'` (default: `'forward'`) | | `config.width` | `number` | Path stroke width | | `config.opacity` | `number` | Path opacity | | `config.label` | `string` | Text label for the flow path | | `config.layer` | `string` | Layer ID this flow path belongs to (default: `'physical'`) | | `config.name` | `string` | Display name for the flow path | ### Example ```javascript topo.flowPath('user-traffic', { waypoints: ['USER1', 'SW1', 'FW1', 'INET'], color: '#01a982', animation: 'particles', speed: 2, direction: 'forward', label: 'User Traffic', layer: 'flow_1', }); ``` ### Bulk Set ```javascript // Set all flow paths at once (e.g. when loading from saved state) topo.setFlowPaths([ ['fp_1', { waypoints: ['A', 'B', 'C'], color: '#01a982' }], ['fp_2', { waypoints: ['X', 'Y'], color: '#65aef9' }], ]); ``` --- ## 37. Policy Markers Policy markers are badges placed on nodes to visualize security or routing policy actions such as inspection, allow, deny, redirect, encryption, and more. ### Registration ```javascript topo.policyMarker(id, config) ``` | Parameter | Type | Description | |-----------|------|-------------| | `id` | `string` | Unique identifier (e.g. `'pm_1'`) | | `config.nodeId` | `string` | The node this marker is attached to | | `config.type` | `string` | Policy action type (see table below) | | `config.color` | `string` | Badge color override | | `config.label` | `string` | Custom label text | | `config.flowPathId` | `string` | Associated flow path ID (optional) | | `config.layer` | `string` | Layer ID this marker belongs to | ### Policy Types | Type | Description | |------|-------------| | `inspect` | Deep packet inspection | | `allow` | Traffic permitted | | `deny` | Traffic blocked | | `redirect` | Traffic redirected | | `encrypt` | Encryption applied | | `decrypt` | Decryption applied | | `nat` | Network address translation | | `load-balance` | Load balancing | | `log` | Logging/auditing | ### Example ```javascript topo.policyMarker('pm-fw-inspect', { nodeId: 'FW1', type: 'inspect', color: '#deb146', label: 'DPI', flowPathId: 'user-traffic', layer: 'policy_1', }); ``` ### Bulk Set ```javascript topo.setPolicyMarkers([ ['pm_1', { nodeId: 'FW1', type: 'inspect', color: '#deb146' }], ['pm_2', { nodeId: 'R1', type: 'allow', color: '#01a982' }], ]); ``` --- ## 38. Layer System Layers group topology elements into visual planes that can be independently toggled, faded, and locked. This enables complex multi-layer visualizations where physical infrastructure, traffic flows, and policy overlays coexist without visual clutter. ### Default Layer Every topology starts with a single default layer: ```javascript { id: 'physical', name: 'Physical', type: 'physical', visible: true, opacity: 1, locked: false, color: '#01a982', order: 0 } ``` ### Registration ```javascript topo.layer(id, config) ``` | Parameter | Type | Description | |-----------|------|-------------| | `id` | `string` | Unique identifier (e.g. `'flow_1'`, `'policy_1'`) | | `config.name` | `string` | Display name | | `config.type` | `string` | Layer type: `'physical'` \| `'flow'` \| `'policy'` | | `config.visible` | `boolean` | Whether the layer is visible (default: `true`) | | `config.opacity` | `number` | Layer opacity 0-1 (default: `1`) | | `config.locked` | `boolean` | Whether elements in this layer can be edited (default: `false`) | | `config.color` | `string` | Accent color for the layer | | `config.order` | `number` | Stacking order (higher = on top) | ### Example ```javascript // Create a flow overlay layer topo.layer('flow_1', { name: 'User Traffic Flow', type: 'flow', visible: true, opacity: 0.8, color: '#65aef9', order: 1, }); // Create a policy layer topo.layer('policy_1', { name: 'Security Policies', type: 'policy', visible: true, opacity: 1, color: '#fc6161', order: 2, }); ``` ### Assigning Elements to Layers Nodes and links can be assigned to a layer via the `layer` property in their configuration: ```javascript topo.node('FW1', { type: 'firewall', x: 300, y: 200, label: 'Firewall', layer: 'physical' }); topo.flowPath('fp_1', { waypoints: ['A', 'B'], color: '#01a982', layer: 'flow_1' }); topo.policyMarker('pm_1', { nodeId: 'FW1', type: 'inspect', layer: 'policy_1' }); ``` ### Bulk Set ```javascript // Replace all layers at once (e.g. when loading from saved state) topo.setLayers([ { id: 'physical', name: 'Physical', type: 'physical', visible: true, opacity: 1, locked: false, color: '#01a982', order: 0 }, { id: 'flow_1', name: 'Traffic', type: 'flow', visible: true, opacity: 0.8, color: '#65aef9', order: 1 }, ]); ``` ### Per-Step Layer Visibility Steps can override layer visibility using the `layerVisibility` property: ```javascript topo.addStep('show-flows', { act: 'a1', name: 'Traffic Flows', goal: 'Visualize traffic patterns.', layerVisibility: { 'flow_1': { opacity: 1 }, // Show flow layer at full opacity 'policy_1': { opacity: 0.3 }, // Dim policy layer }, phases: [{ show: ['FW1'], diff: 'Firewall visible' }], }); ``` The engine walks backwards from the current step to find the most recent `layerVisibility` override for each layer. --- ## 39. Export (PNG / SVG / PDF / Standalone HTML) Topology Studio can export the current canvas state as a high-resolution PNG, a vector SVG, or a PDF. Export works from both the visual editor's **File** menu and programmatically via the API. ### API #### `topo.exportPNG()` Exports the current step's diagram as a PNG file. The output is rendered at **2400 px wide** (aspect-ratio-preserving), with the dark background (`#1d1f27`) filled in. The file is downloaded automatically with a sanitized version of the topology title as the filename. ```javascript await topo.exportPNG(); // Downloads: "My_Network.png" at 2400×1371px (for a 1050×700 viewBox) ``` > **Note:** `exportPNG()` is `async` because it rasterises the SVG through an `` + `