diff --git a/content/en/kanvas/advanced/autopan/index.md b/content/en/kanvas/advanced/autopan/index.md new file mode 100644 index 00000000000..f84da1b84e0 --- /dev/null +++ b/content/en/kanvas/advanced/autopan/index.md @@ -0,0 +1,115 @@ +--- +title: Auto-pan on Drag +description: > + Kanvas automatically pans the viewport while you drag a component past the canvas edge. Learn when it helps, how to toggle it, and the performance gates that decide when it stays active. +weight: 3 +categories: [Designer] +tags: [performance, interaction] +--- + +**Auto-pan on Drag** (autopan, for short) is the behavior where Kanvas scrolls the canvas for you when you drag a component close to — or past — the visible edge. Instead of having to stop, let go, scroll the canvas, grab the component again, and continue, you keep dragging and the canvas glides along with you. + +Autopan is the difference between **"move this component to another part of the design"** being one continuous gesture vs. four separate ones. It is on by default in the Designer, and you can turn it off any time in the **Options** panel. + +## Why Auto-pan Matters + +Kanvas designs often grow past the size of your viewport. A microservices topology, a multi-cluster Kubernetes landscape, or a Helm-chart expansion can easily produce a design that is ten or twenty screens wide at typical zoom. Without autopan, moving a component from one side of that canvas to the other means: + +1. Grab the component. +2. Drag it to the edge of the visible canvas. +3. Release the mouse button. +4. Pan the canvas using two-finger scroll, the middle mouse button, or the on-screen navigation controls. +5. Re-grab the component — which is now well inside the viewport again. +6. Drag it to the next edge. +7. Repeat until you reach the destination. + +With autopan enabled, the same action is a single uninterrupted drag. Kanvas detects that the component is leaving the viewport and scrolls the camera in the direction you are dragging, so you never run out of canvas. The further past the edge you push, the faster the canvas pans. + +Autopan is most valuable when: + +- **Re-organizing large designs.** Moving a node from one cluster to another, relocating a group, or reshaping the layout of a design that doesn't fit on screen. +- **Drag-based edge creation.** Pulling a relationship handle from a source component toward a target that is off-screen. +- **Compound drag-and-drop.** Dropping a child component into a parent group that sits past the viewport edge — the autopan keeps the drop target in view as you approach it. + +It is least valuable (and most expensive) when: + +- The design is **fully visible without scrolling**. There is nothing past the viewport to pan to. +- The design is **very large and very detailed**. Every pan triggers a rerender of the canvas, every badge, and every overlay. On a 500-node design in Full render mode, that cost shows up as input lag. + +Kanvas is aware of both cases. The first is harmless — autopan simply never activates because the drag never reaches the edge. The second is managed by **per-render-mode performance gates**, covered below. + +## Toggling Auto-pan + +Open the **Options** panel (the gear icon in the Designer toolbar) and look under **Canvas Settings** for **Auto-pan on Drag**. + +- **On (default)** — autopan activates when you drag past the viewport edge, subject to the per-render-mode size gate. +- **Off** — autopan never activates. You pan manually. + +The toggle takes effect immediately. You do not need to refresh the page or re-open the design. If autopan was already running when you flipped the switch, it detaches its drag listeners on the spot; if it was off and you turn it on, it re-attaches them. The switch is per-user (stored as a user preference in your Kanvas profile), so the setting follows you across devices. + +{{< alert type="info" title="Finding the setting" >}} +The toggle lives in the **Options** modal under **Canvas Settings**. If you don't see it, make sure you're in Designer mode — autopan is a Designer-only feature because it affects component dragging, which is disabled in read-only Operator views. +{{< /alert >}} + +## Advanced Performance Considerations + +Autopan is cheap on a small graph and expensive on a large one. The reason is not the autopan extension itself — that work is constant per drag event — but the chain of listeners that react when the canvas pans. + +### What autopan actually does under the hood + +When you drag a component near the edge of the viewport, the `cytoscape-autopan-on-drag` extension listens for each pointer-move event. If the component has crossed the viewport boundary, it calls `cy.panBy(…)` on the canvas engine. That single call produces a `pan viewport` event inside Cytoscape, which fires **every** listener that is subscribed to that event. + +In a production Kanvas Designer, those listeners include: + +- **Grid redraw** — the gridGuide extension re-renders the dotted grid at the new viewport origin. +- **Badge and overlay re-layout** — validation warning badges, deployment error badges, inventory badges, comment markers and connection handles are all positioned in canvas space and need to be re-positioned when the camera moves. +- **React state updates from the overlay hook** — overlays that are rendered in the DOM (not on the canvas) need React to push their new screen positions. +- **Renderer dirty-paints** — Cytoscape's internal renderer marks the canvas dirty and schedules a repaint. + +Each of those listeners is individually cheap, but they all scale with the number of nodes and edges on the canvas. A single pan on a 1,000-node design does roughly ten times as much work as the same pan on a 100-node design. + +Pointer-move events fire fast — up to around 120 times a second on high-refresh-rate trackpads. The per-event budget for a smooth 60 fps interaction is about 16 milliseconds, and pointer-move dispatch eats into that budget. When the work done by downstream listeners gets too expensive, autopan stops being a feature and starts being a source of input lag. + +### Why the threshold depends on the render mode + +Not every Kanvas render mode attaches the same listeners to the pan event. In **Full** mode, every overlay, every badge, and the grid are all live. In **Medium**, overlays and badges are suppressed — the grid and renderer are still active. In **Wireframe** and **View-Only**, even the grid is dropped, leaving only the renderer's own paint. + +Since the per-mode listener fan-out differs by a factor of roughly four between Full and Wireframe, the graph size at which autopan starts to lag also differs by about that factor. Kanvas encodes this in a per-mode threshold table, applied automatically: autopan disables itself when the graph exceeds the threshold for the current render mode. + +| Render mode | Safe node/edge count with autopan | Rationale | +| ---------------------- | --------------------------------: | ------------------------------------------------------------------------ | +| Full | 100 | Grid + badges + overlays + renderer all react to every pan | +| Medium | 500 | Badges and overlays suppressed — ~2× fan-out reduction | +| Wireframe | 1,000 | Grid and overlays suppressed — only the renderer paints | +| View-Only | 1,000 | Same fan-out profile as Wireframe, non-interactive | + +These numbers are empirical — derived from the `autopanPerf_spec.ts` performance-gate test, which measures per-event cost across listener fan-outs and asserts that each threshold stays within the per-event budget. If you modify a downstream listener to do more work on pan (for example, you add a new badge type that redraws on every viewport change), the test will flag which thresholds need to move. + +### Automatic disable and re-enable + +Autopan is not a static decision taken when you load a design. Kanvas re-evaluates the gate continuously: + +- **When the graph grows past the threshold** — for example, paste in a large subtree, import a design fragment, or accept a collaborator's bulk update — Kanvas detects the new element count and disables autopan on the next animation frame. Bursty operations are coalesced into a single re-evaluation rather than thrashing through enable/disable on every element. +- **When the graph shrinks back under the threshold** — deleting elements or cutting a subgroup drops the count. Kanvas notices and re-enables autopan if your preference allows it. +- **When you switch render mode** — switching from Full to Wireframe on the same design can shift the gate from "disabled" to "enabled" because the threshold is higher in Wireframe. Kanvas re-evaluates and applies the right state instantly. +- **When you flip the preference** — toggling **Auto-pan on Drag** in the Options panel takes effect immediately without a remount. + +This is driven by the shared `useReactiveFeatureGate` hook in Kanvas's source, which any future feature gated by (user preference × render mode × graph size) can reuse. + +{{< alert type="note" title="When autopan is disabled automatically" >}} +If you are working on a large design and autopan seems to not kick in at the edge, check the [Render Modes](/kanvas/advanced/render-modes/) page. Your graph has probably exceeded the threshold for the current render mode and Kanvas has disabled autopan for performance. You can either switch to a lower-fidelity render mode — which raises the threshold — or pan manually for the remaining operations. +{{< /alert >}} + +### Tuning autopan for your design + +If autopan is disabled on a design where you would like it to be active, you have three levers: + +1. **Switch to a lower-fidelity render mode.** Wireframe and View-Only raise the threshold to 1,000 nodes. See the [Render Modes](/kanvas/advanced/render-modes/) page for what each mode costs and what it hides. +2. **Reduce the live listener count.** The [Layers Panel](/kanvas/advanced/performance/) lets you disable layers of visual information (badges, tags, feasibility indicators) that contribute to the pan fan-out. Turning off a layer effectively moves the threshold upward because there are fewer listeners to amplify each pan. +3. **Break the design into smaller designs.** If you are consistently bumping the threshold in your preferred render mode, the design might be past the scale Kanvas targets for interactive editing. Splitting it into referenced sub-designs keeps each one within the sweet spot. + +### Related pages + +- [Render Modes](/kanvas/advanced/render-modes/) — what each mode renders, what it hides, and how Adaptive Render Mode flips between them automatically. +- [Performance Limits and Tuning](/kanvas/advanced/performance/) — overall Kanvas performance envelope and the Layers Panel. +- [Design Render Quality](/kanvas/advanced/url-parameters/) — overriding the render mode via URL parameters (useful for snapshots and embeds). diff --git a/content/en/kanvas/advanced/render-modes/index.md b/content/en/kanvas/advanced/render-modes/index.md index 97f77a9413f..c985403e3b9 100644 --- a/content/en/kanvas/advanced/render-modes/index.md +++ b/content/en/kanvas/advanced/render-modes/index.md @@ -1,177 +1,239 @@ --- title: Render Modes description: > - Control rendering fidelity and performance in Kanvas with four render modes and an intelligent Adaptive mode that automatically optimizes the experience. -weight: 3 + Kanvas renders a design at four distinct levels of detail. Learn what each render mode shows, what it hides, the feature size gates tied to each mode, and how Adaptive Render Mode picks the right one automatically based on live performance signals. +weight: 4 categories: [Designer, Operator] tags: [performance, rendering] --- -Kanvas supports multiple render modes that control the level of visual detail and interactivity on the canvas. Higher-fidelity modes show more detail but require more processing power, while lower-fidelity modes strip visual elements for better performance on large designs. +Kanvas can draw the same design at **four different levels of visual fidelity**. The level is called the **render mode**, and it controls how much of Kanvas's visual machinery — badges, overlays, textures, grid, relationship animations — actually runs on each frame. Lower-fidelity modes paint less, so they stay fast on larger designs. Higher-fidelity modes show everything, which is what you want on a design you're polishing or presenting. -The Adaptive mode acts like an automatic transmission -- it monitors render performance in real time and seamlessly shifts between modes to maintain smooth interactivity. +The render mode is a **performance tool**, not a document property. Switching modes does not change your design — components, relationships, layers, and metadata are identical. It only changes what Kanvas chooses to render on screen. -## Render Modes +## The four render modes -Kanvas provides four render modes, each offering a different balance of visual fidelity and performance: +You can switch modes through the **render-mode switcher** in the Options panel (the gear icon on the toolbar, at the bottom of the dialog). Each mode has a distinct purpose. -| Mode | Fidelity | Description | -|------|----------|-------------| -| Full | Highest | Complete rendering with all details, badges, TagSets, animations | -| Medium (Style-Only) | High | Full component styles but no badges, TagSets, or animations | -| Wireframe | Low | Simple outlines and straight-line connections, no SVGs or styling | -| View Only | Lowest | Static wireframe snapshot with no interactivity | +### Full -### Full Mode +**Use when:** finalizing a design, reviewing it with colleagues, publishing, exporting a snapshot, working on the visual polish. -Full mode renders every visual element in your design: +**What renders:** everything Kanvas has — SVG backgrounds and gradient fills, component icons with full texture, feasibility indicators, all badges (compound node, label, external link, expand/collapse, managed-by-Meshery, terminal session, and error badges), TagSets (BubbleSets), mount animations, relationship animations with bezier curves and colored arrows, grid lines, compound-group outlines, and hover overlays. Labels render in their full fidelity with font rendering and shadows where applicable. -- **SVG backgrounds** and gradient fills on all components -- **All badges** -- compound node, label, external link, expand/collapse, managed-by-Meshery, terminal session, and error badges -- **TagSets** (BubbleSets) showing visual groupings of related components -- **Mount animations** when components appear on the canvas -- **Edge styling** with bezier curves and colored arrows +**Cost:** highest. Every pan, zoom, or layout update touches every overlay and badge in the visible area. Designed to look best, not go fastest. -Full mode is best for reviewing final visuals, detailed inspection, and pixel-perfect output. It uses the most resources and may impact performance on large or complex designs. +**Default:** this is the default mode when you open a design unless adaptive mode has downshifted you — see below. -### Medium Mode (Style-Only) +### Medium -Medium mode preserves component appearance while stripping decorative overlays: +**Use when:** day-to-day editing, adding or arranging components, when you want enough detail to orient yourself but not every live overlay running. -- **Kept:** Component SVG backgrounds, node shapes, and edge styling -- **Kept:** Expand/collapse badges (essential for navigating compound nodes) and error badges -- **Stripped:** Decorative badges (compound node, label, external link, managed-by-Meshery, terminal session) -- **Stripped:** TagSets, mount animations, and gradient fills +**What renders:** component SVG backgrounds, node shapes, edge styling, expand/collapse badges (essential for navigating compound nodes), error badges, and core interactions. **Suppressed:** decorative badges (compound node, label, external link, managed-by-Meshery, terminal session), TagSets, mount animations, gradient fills, validation / inventory badges, and feasibility indicators. You keep the visual identity of each component but stop paying the per-frame cost of re-positioning dozens of badges. -Medium mode is ideal for everyday editing where you want to see component detail without visual clutter. It is significantly lighter than Full mode. +**Cost:** moderate. Fan-out on pan/zoom is roughly half of Full because the badge and overlay layers don't react to every viewport change. -### Wireframe Mode +### Wireframe -Wireframe mode reduces the canvas to basic structural outlines: +**Use when:** working with large designs where structure matters more than detail, doing layout passes, or exporting simplified views. Also the right mode when you are about to pan or zoom heavily on a design with hundreds of components. -- **No SVG background images** on any components -- **Edges rendered as straight gray lines** -- no bezier curves or colored arrows -- **All badges stripped** -- **All TagSets disabled** -- **Layout animations disabled** +**What renders:** component outlines, component shapes, and relationships as straight gray lines. **Suppressed:** SVG background images, textures, images, bezier-curve edge styling, badges, overlays, layout animations, TagSets, and most styling. The canvas effectively becomes a schematic of your design. -Wireframe mode is best for quick layout work, performance-critical scenarios, and focusing purely on design structure. It is very lightweight and handles large designs well. +**Cost:** low. Only the renderer paints; no badges, no overlays, no image decoding. -### View Only Mode +### View-Only -View Only mode extends Wireframe rendering with complete removal of interactivity: +**Use when:** embedding a design, sharing a read-only snapshot, presenting a design to an audience, or viewing a design where nobody should be able to accidentally edit. -- Same visual rendering as Wireframe mode -- **All nodes locked** -- cannot be moved or resized -- **All event handlers removed** -- no click, hover, grab, drag, resize, or double-click responses +**What renders:** the same minimal set as Wireframe — outlines, shapes, relationships — but with **every interactive affordance disabled**. All nodes are locked (cannot be moved or resized), all event handlers are removed (no click, hover, grab, drag, resize, or double-click responses), and no keyboard shortcuts that would mutate the design are active. The canvas is visible and pannable but not editable. -View Only mode is best for embedding designs, sharing read-only views, and generating static documentation screenshots. It uses minimal resources. +**Cost:** lowest. Same paint budget as Wireframe plus the interaction layer is disabled entirely. {{< alert type="info" >}} In View Only mode, users cannot interact with the canvas at all. Switch to another mode to resume editing. {{< /alert >}} -## Switching Render Modes +{{< alert type="note" title="Render mode vs. Operator mode" >}} +Don't confuse render mode with **Operator mode**. Operator mode is a separate top-level mode of Kanvas (alongside Designer mode) that visualizes **live infrastructure** rather than authored designs. Render mode is orthogonal — it works the same way inside Designer and Operator. +{{< /alert >}} + +## Switching render modes -### Using the Layers Panel +### Using the Options panel -The **Render Mode Switcher** is located in the Layers panel in the left sidebar. To change modes: +The **Render Mode Switcher** is located in the Options panel (the gear icon on the toolbar). To change modes: -1. Click the current mode icon in the Layers panel to open the mode selector. -2. Select the desired mode from the dropdown menu. -3. The canvas updates immediately. +1. Open the Options panel from the toolbar. +2. Click the current mode to open the mode selector. +3. Select the desired mode. The canvas updates immediately. -### Using URL Parameters +### Using URL parameters You can also set the render mode via URL query parameter. Append the `render` parameter to your Kanvas design URL: -- `render=full` -- Full rendering with all details -- `render=medium` -- Style-only rendering without badges and TagSets -- `render=wireframe` -- Outline-only rendering -- `render=viewOnly` -- Non-interactive wireframe snapshot +- `render=full` — Full rendering with all details +- `render=medium` — Style-only rendering without badges and TagSets +- `render=wireframe` — Outline-only rendering +- `render=viewOnly` — Non-interactive wireframe snapshot For example: `https://kanvas.new/extension/meshmap?render=wireframe&mode=design&design=xxxx` For more details on URL parameters, see [Design Render Quality](/kanvas/advanced/url-parameters/). -## Adaptive Mode +## Feature size gates by render mode -Adaptive mode automatically adjusts the render mode based on real-time performance measurements. When enabled, Kanvas monitors canvas responsiveness and shifts between modes to maintain smooth interactivity -- downshifting when performance degrades and upshifting when it recovers. +Several Kanvas features are too expensive to run unconditionally on large graphs. Each gated feature has a **size threshold** — a node/edge count past which the feature disables itself for the current render mode. The threshold is chosen for the amount of work that feature does per frame and the listener fan-out at that render mode. -### How It Works +Threshold table: -Adaptive mode monitors two performance metrics in real time: +| Feature | Full | Medium | Wireframe | View-Only | Notes | +| ---------------------------- | -----------------------: | -----------------------: | -----------------------: | -----------------------: | ----------------------------------------------------------------------------------------------- | +| **Auto-pan on Drag** | 100 | 500 | 1,000 | 1,000 | See [Auto-pan on Drag](/kanvas/advanced/autopan/). | +| **Layout animation** | 100 | —¹ | —¹ | —¹ | Animated layouts only run in Full mode with ≤100 edges. | +| **TagSet visual grouping** | 20² | 20² | 20² | 20² | TagSets display auto-disables past 20 tags; re-enable via **Group Components** in the dock. | +| **Feasibility evaluation** | zoom-gated³ | zoom-gated³ | zoom-gated³ | zoom-gated³ | Gated on zoom, not size — hidden when you zoom out past the detail threshold. | +| **Component style editing** | zoom-gated³ | zoom-gated³ | zoom-gated³ | zoom-gated³ | Same: revealed only at detailed zoom levels. | -- **Render latency** -- the time to complete a render cycle (measured at the p95 percentile) -- **Interaction latency** -- the time from user input (pan, zoom) to visual response (measured at the p95 percentile) +¹ *Layout animation is a Full-mode-only feature by design. Kanvas falls back to instant (unanimated) layouts in other modes, so the per-mode threshold doesn't apply.* +² *TagSet threshold is tag count, not node count. See [Working with Tags](/kanvas/designer/tagsets/).* +³ *Zoom-gated features activate when your zoom level is above `MIN_ZOOM_FOR_DETAILED_RENDERING`. Zooming out suppresses them regardless of render mode.* -Performance is tracked using a rolling window of the last 20 samples. When the p95 render latency exceeds 150ms or the p95 interaction latency exceeds 80ms, the mode automatically downshifts (for example, Full to Medium, or Medium to Wireframe). When performance recovers -- render latency drops below 60ms and interaction latency drops below 30ms for 10 consecutive samples -- the mode upshifts. +### How size gates interact with render modes -### Hysteresis (Preventing Flicker) +Two rules to remember: -Adaptive mode uses asymmetric thresholds to prevent rapid mode switching: +1. **Lower-fidelity render modes raise the size threshold.** Moving from Full to Wireframe is a ten-fold increase in the autopan threshold, because Wireframe isn't doing the badge and overlay work that dominates the pan cost in Full. The same design that feels laggy under Full autopan can feel fine under Wireframe autopan. -- **Downshifting happens quickly** -- with a 3-second cooldown between shifts. Users notice lag immediately, so the system responds fast. -- **Upshifting is cautious** -- requiring 10 consecutive good samples before shifting up. This prevents the mode from flickering back and forth at the boundary. +2. **Every gate is bidirectionally reactive.** If a gated feature was off because your graph was too big, and you then delete components, cut a subgroup, or simply switch render modes, Kanvas notices and re-enables the feature on the spot. You never need to refresh or re-open the design to recover a feature you've lost to a threshold. -The result is fast response to performance problems and careful, stable recovery. +### How to check whether a feature is gated off -### Ceiling Mode +The render-mode switcher shows the current mode, and each gated feature exposes its own state — the autopan toggle in Options is a boolean preference, not a live status light. If something feels like it should be working and isn't, the fastest check is: -When you enable Adaptive mode, your currently selected render mode becomes the **ceiling** -- the highest fidelity that Adaptive will use. Adaptive mode will never upshift above your ceiling. +1. Look at the current render mode in the switcher. +2. Count roughly how many components/relationships are in your design. +3. Cross-reference with the threshold table above. -For example, if you set the ceiling to Medium, Adaptive will shift between Medium and Wireframe as needed but will never go to Full mode. This is useful when you know you do not need badges or tagsets and want to prevent unnecessary rendering overhead. +If you're past the threshold for the mode, the feature is gated off. Switch render modes or shrink the graph to get it back. -### Enabling Adaptive Mode +## Adaptive Render Mode -To enable Adaptive mode: +**Adaptive Render Mode** is Kanvas's automatic fidelity-management system. Instead of you picking a render mode manually and living with it, Kanvas watches its own performance telemetry and slides the render mode up or down to match real conditions — your machine, your browser, your current design's size, and whatever else is running on the page. -1. Open the **Render Mode Switcher** in the Layers panel. -2. Toggle the **Adaptive** switch. -3. When active, an "AUTO" indicator appears next to the current mode. +### How to turn it on -Manual mode selections while Adaptive is active set the new ceiling. For example, switching from Full to Medium while Adaptive is on means Adaptive will now treat Medium as the highest mode it can use. +In the render-mode switcher (Options panel), there is an **Adaptive** toggle at the top. Flip it on and Kanvas enters adaptive mode. Instead of selecting a render mode directly, the mode you pick in the switcher becomes the **ceiling** — the maximum fidelity adaptive mode is allowed to use. An `AUTO` chip appears next to the current mode so you know adaptive is driving. + +If you pick Full as your ceiling, adaptive mode will use Full when performance allows and downshift to Medium or Wireframe when it needs to. If you pick Medium as the ceiling, it will never go above Medium but will still downshift to Wireframe under load. You can also enable Adaptive mode via URL parameter: `?adaptive=true` For example: `https://kanvas.new/extension/meshmap?adaptive=true&mode=design&design=xxxx` +### What signals does adaptive mode watch? + +Kanvas's performance monitor emits a rolling window of samples covering two latency metrics: + +- **Render latency** — the time it takes to paint a single frame (measured at the p95 percentile). +- **Interaction latency** — the time between a user input (pan, zoom, click, drag, hotkey) and the visible response (measured at the p95 percentile). + +Both are tracked as **p95** across a rolling window of the last 20 samples, so a one-off hiccup doesn't trigger a mode change — the metric has to stay bad across many frames before adaptive reacts. + +Two thresholds on each metric govern the decision: + +- **Downshift** — p95 render latency above about 150 ms, or p95 interaction latency above about 80 ms, means the current mode is too expensive. Adaptive moves to the next lower mode after a short 3-second cooldown. +- **Upshift** — p95 render latency below about 60 ms **and** p95 interaction latency below about 30 ms, sustained across 10 consecutive good samples, means there is headroom to paint more detail. Adaptive moves to the next higher mode (capped by your ceiling) after a longer delay. + +The downshift is fast because a laggy canvas is an immediate problem; the upshift is deliberately slow because you don't want to bounce back into Full the moment things calm down, only to downshift again three seconds later. + {{< alert type="note" >}} -Adaptive mode is event-driven -- it only samples performance when you interact with the canvas (pan, zoom, edit). There is zero overhead when the canvas is idle. +Adaptive mode is event-driven — it only samples performance when you interact with the canvas (pan, zoom, edit). There is zero overhead when the canvas is idle. {{< /alert >}} -## Performance Guidance +### The mode ladder + +Adaptive mode climbs and descends this ladder: + +``` +Full ↕ Medium ↕ Wireframe +``` + +View-Only is **not** part of the ladder. It is a deliberate operator choice (for embedding, sharing, or presenting) rather than a performance tier, so adaptive mode never drops you into View-Only automatically. + +### Cooldowns and debouncing + +Mode changes are throttled: + +- After a downshift, adaptive waits before considering the next change. This prevents a runaway descent from Full → Medium → Wireframe in a single bad second. +- Upshifts require a **sustained** run of good samples. A momentary improvement doesn't pull you back up to Full. + +The combination keeps adaptive mode stable — it reacts to real performance trends, not individual frame jitter. + +### When to use adaptive mode + +Adaptive is the right default for most users. Turn it on once and forget about it; Kanvas picks the mode that keeps interactions snappy. You only need to revisit the ceiling when: + +- **You want to cap the fidelity** — for example, on a shared machine where you know you'll always be below Full capability. Set the ceiling to Medium. +- **You are presenting or exporting** — for a screenshot, a demo, or a final review, you want a deterministic render mode. Turn adaptive off and pick Full manually so you're not midway through a mode transition when you take the screenshot. +- **You are debugging a performance problem** — turning adaptive off and manually selecting each mode gives you a clean A/B comparison to isolate what is actually causing the slowdown. + +### When to turn it off + +Adaptive mode is dynamic by design. That means the canvas you're looking at may change fidelity between one minute and the next. Turn it off when: + +- You are **recording a video or capturing screenshots** where mid-capture mode changes would be distracting. +- You are **teaching or demoing** Kanvas and you want viewers to see a specific render mode. +- You are **comparing two designs** side-by-side and you want to be sure they are both rendered at the same fidelity. + +## Performance guidance When Adaptive mode downshifts, Kanvas may display suggestions to help you optimize your design. These appear as toast notifications with actionable recommendations: -- **"N tagsets detected"** -- Large numbers of TagSets (BubbleSets) are computationally expensive. Consider disabling some via the Layers panel. -- **"N parent nodes detected"** -- Deeply nested compound nodes increase render complexity. Collapsing some parent nodes may help. -- **"N components visible"** -- High-density designs benefit from layer filtering to hide components you are not currently working with. -- **"N relationships"** -- Designs with many relationships render faster in Wireframe mode. +- **"N tagsets detected"** — Large numbers of TagSets (BubbleSets) are computationally expensive. Consider disabling some via the Layers panel. +- **"N parent nodes detected"** — Deeply nested compound nodes increase render complexity. Collapsing some parent nodes may help. +- **"N components visible"** — High-density designs benefit from layer filtering to hide components you are not currently working with. +- **"N relationships"** — Designs with many relationships render faster in Wireframe mode. Each suggestion is shown at most once per minute to avoid notification fatigue. -## Best Practices +## Cheat sheet + +| If you want to… | Do this | +| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | +| Keep the canvas snappy without thinking about it | Turn on **Adaptive** with **Full** as the ceiling. | +| Polish a design visually before sharing | Turn off Adaptive. Pick **Full** manually. | +| Lay out a 500+ component design efficiently | Switch to **Wireframe** for the layout pass, then bump back to Medium or Full for the detail pass. | +| Share a read-only view | Pick **View-Only** and share the design URL. | +| Recover autopan that stopped working | Either switch to a lower-fidelity render mode or delete/hide components to drop below the per-mode size threshold. | +| Make a snapshot with all badges and TagSets forced visible | Use `?render=full` in the URL — see [Design Render Quality](/kanvas/advanced/url-parameters/). | -1. **Start with Adaptive mode** for everyday work -- it handles performance automatically and keeps the canvas responsive. -2. **Use Full mode selectively** -- reserve it for final visual review or documentation screenshots. -3. **Switch to Wireframe for layout work** -- it is the fastest mode for rearranging large designs. -4. **Use View Only for sharing** -- when embedding designs or sharing read-only snapshots where editing should be prevented. -5. **Set an appropriate ceiling** -- if you do not need badges or tagsets, set the ceiling to Medium to avoid unnecessary rendering overhead. -6. **Break large designs into smaller ones** -- designs beyond 500 components benefit from being split regardless of render mode. See [Performance Limits and Tuning](/kanvas/advanced/performance/) for more guidance. +## Best practices -## Known Limitations +1. **Start with Adaptive mode** for everyday work — it handles performance automatically and keeps the canvas responsive. +2. **Use Full mode selectively** — reserve it for final visual review or documentation screenshots. +3. **Switch to Wireframe for layout work** — it is the fastest mode for rearranging large designs. +4. **Use View Only for sharing** — when embedding designs or sharing read-only snapshots where editing should be prevented. +5. **Set an appropriate ceiling** — if you do not need badges or tagsets, set the ceiling to Medium to avoid unnecessary rendering overhead. +6. **Break large designs into smaller ones** — designs beyond 500 components benefit from being split regardless of render mode. See [Performance Limits and Tuning](/kanvas/advanced/performance/) for more guidance. -- Render mode applies globally to the entire canvas -- you cannot set different modes for different areas of a design. +## Known limitations + +- Render mode applies globally to the entire canvas — you cannot set different modes for different areas of a design. - View Only mode strips all interactivity. You must switch to another mode to resume editing. - Adaptive mode thresholds are fixed and cannot be customized per-user or per-design. - Mode transitions may cause a brief visual flash as styles update across all elements. -- The performance guidance system analyzes design structure, not actual GPU or CPU load -- suggestions are heuristic-based. +- The performance guidance system analyzes design structure, not actual GPU or CPU load — suggestions are heuristic-based. -## Render Modes in Designer vs Operator +## Render modes in Designer vs Operator All four render modes work in both Designer and Operator contexts: - In **Designer mode**, render modes control the fidelity of your editable design canvas. All modes except View Only allow full editing. -- In **Operator mode**, the `managed-by-Meshery` and `terminal session` badges follow the same suppression rules as in Designer -- they are visible in Full mode and hidden in Medium, Wireframe, and View Only modes. +- In **Operator mode**, the `managed-by-Meshery` and `terminal session` badges follow the same suppression rules as in Designer — they are visible in Full mode and hidden in Medium, Wireframe, and View Only modes. - **View Only mode is particularly useful in Operator** for monitoring dashboards where accidental edits should be prevented. + +## Related pages + +- [Auto-pan on Drag](/kanvas/advanced/autopan/) — the most visible feature gated per render mode. +- [Performance Limits and Tuning](/kanvas/advanced/performance/) — full performance envelope and the Layers Panel. +- [Design Render Quality](/kanvas/advanced/url-parameters/) — URL parameter overrides for render mode.