Repository navigation
docs(kanvas): document embed stylesheet and both adaptive render latency signals #1380
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: master
Are you sure you want to change the base?
Changes from all commits
57faf48
c09f3c2
43e0c8d
233be83
c713951
404bddc
34775f2
fe1366c
26754db
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -124,9 +124,9 @@ If you're past the threshold for the mode, the feature is gated off. Switch rend | |
|
|
||
| ### How to turn it on | ||
|
|
||
| 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. | ||
| 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. Turning Adaptive on sets the canvas to the ceiling at once (Full, unless you chose another). | ||
|
|
||
| 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. | ||
| 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. Changing the ceiling while Adaptive is already on does not change the running behavior until you turn Adaptive off and on. | ||
|
|
||
| You can also enable Adaptive mode via URL parameter: `?adaptive=true` | ||
|
|
||
|
|
@@ -136,20 +136,20 @@ For example: `https://kanvas.new/extension/meshmap?adaptive=true&mode=design&des | |
|
|
||
| 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). | ||
| - **Render latency** - the time Kanvas takes to apply one update to the canvas, such as an edit, a layout change, or a collaborator's change arriving (measured at the p95 percentile). | ||
| - **Interaction latency** - how long the canvas takes to show the next frame after you pan or zoom (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. | ||
| Each metric keeps its own rolling window of the last 20 samples and is tracked as **p95** across that window. A metric can trigger a downshift only once its window holds 20 samples, so a single slow sample, such as the render pass that loads a large design, cannot downshift on its own. Because p95 of 20 samples is the second-slowest one, a full window needs at least two slow samples among the last 20 before adaptive reacts. Both windows are cleared on every mode change - each downshift and upshift - and when you turn Adaptive on, so each mode is judged only on its own samples. | ||
|
|
||
| Two thresholds on each metric govern the decision: | ||
|
|
||
| - **Downshift.** When the 95th percentile of the last 20 frame times exceeds 80 ms, Kanvas drops one step and ignores samples for 3 seconds. The signal is how long the canvas takes to produce the next frame after a pan or zoom. Kanvas does not use a separate 150 ms render threshold. | ||
| - **Upshift.** When that percentile stays under 30 ms for 10 consecutive samples, more than 5 seconds after the last change, and the next mode is not above the ceiling. Recovery is at most one step until the next slowdown. | ||
| - **Downshift.** When the render window is full and its p95 exceeds 150 ms, or the interaction window is full and its p95 exceeds 80 ms, Kanvas drops one step, ignores samples for 3 seconds, and notifies you: "Switched to *mode* mode for better performance". Either metric alone is enough, so a run of slow edits or collaborator updates can trigger a downshift just as laggy panning or zooming can. | ||
| - **Upshift.** When at least one window is full, p95 render latency stays under 60 ms and p95 interaction latency stays under 30 ms for 10 consecutive samples, more than 5 seconds after the last change, and the next mode is not above the ceiling. Both metrics must be good: in a window that is not yet full, every sample must be under its budget, and an empty window counts as under. Kanvas steps up one mode and notifies you: "Performance improved - switched to *mode* mode". Recovery is at most one step until the next slowdown. | ||
|
|
||
| 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 the canvas does work: when you pan or zoom, or when an update such as an edit is rendered. There is zero overhead when the canvas is idle. | ||
| {{< /alert >}} | ||
|
|
||
| ### The mode ladder | ||
|
|
@@ -160,16 +160,16 @@ 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. | ||
| 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, and never moves you out of it. | ||
|
|
||
| ### 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. | ||
| - After a downshift, adaptive ignores samples for 3 seconds, and the cleared windows must fill again with samples from the new mode before it can downshift again. This prevents a runaway descent from Full → Medium → Wireframe in a single bad second. | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Clarify which window must refill. After a downshift, Line 146 says a full render window can trigger another downshift even if the interaction window is empty. This sentence says the cleared windows must fill, which implies both are required. State that the triggering metric's window must refill.
|
||
| - 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. | ||
| The combination keeps adaptive mode stable — it reacts to real performance trends, not one-off slow samples. | ||
|
|
||
| ### When to use adaptive mode | ||
|
|
||
|
|
@@ -181,7 +181,7 @@ Adaptive is the right default for most users. Turn it on once and forget about i | |
|
|
||
| ### 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: | ||
| Adaptive mode is dynamic by design. That means the canvas you're looking at may change fidelity between one minute and the next. Turning it off keeps the mode Adaptive last chose. 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. | ||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Clarify the View-Only exception.
This says enabling Adaptive immediately sets the canvas to the ceiling. Line 163 says Adaptive never moves the canvas out of View-Only. Clarify what happens if Adaptive is enabled while View-Only is active, or state if that action is unavailable.