--- id: "canvas.desempenho-e-memoria" titulo: "Canvas performance and memory" resumo: "What the Canvas does to keep a large board usable — and what you can observe when a card leaves the screen." idioma: "en" tipo: "conceito" categoria: "telas" aplicavelDesde: "0.0.16" capabilities: ["canvas.cards.body-energy", "canvas.performance.instrumentation"] estadoEditorial: "aprovado" nivelEvidencia: "artefato-distribuido" refFonte: "27574c339b58316408f6be2d62169d59041d07bf" revisaoFonte: "2026-09-24" revisor: "mantenedor (v1, 2026-10-03)" rota: "/docs/en/canvas/desempenho-e-memoria/" fonte: "pt-br/canvas/desempenho-e-memoria.md" caminhoPublico: "docs/publica/en/canvas/desempenho-e-memoria.md" hashFonte: "sha256:6cfed6075fd81a7c9f523f05bec19af306c8a8402060fb0392e5d10905824700" hashDestaPagina: "sha256:d4129eba735badd095c36ab68c5f1ce70f6b73d7c393a1e016163e655fea07a3" traducaoAssistidaPorIA: true traducaoDesatualizada: false corpoRetido: false --- A board with many cards is expensive: every terminal is a process and a buffer, every editor is a tree of elements on screen. This page explains what the app does to keep the board usable — and what that means for you. > **None of this is a setting.** There is no Canvas performance option to turn on, turn off or tune. It is internal app policy. ## The idea: energy per card Every card has an **energy level**, computed from where it sits relative to the visible area, from its window state (normal or minimized) and from internal limits: | Level | What it means | |---|---| | **Active** | In the visible area and painting in full. | | **Warm** | Mounted and ready, with painting suspended while off screen. | | **Suspended** | The card was **minimized**: the body leaves the screen, but the content **stays alive**. | | **Parked** | The card stays outside the visible area **past the hysteresis time**: same effect as suspended, for a different reason. | | **Evicted** | The content was destroyed on screen; the **session stays alive** in the main process. | The central point: **the session never dies because of energy**. A terminal off screen keeps receiving whatever the process writes; a conversation stays the same. What changes is how much screen work the card costs. ## Which cards can be suspended > **Terminal cards only.** Notes, files, conversations and browsers are **never** suspended or evicted: their body stays mounted at all times. A note's text does not disappear because of performance. ## The internal limits - There is a **ceiling of 50 bodies** suspended or parked at the same time. Past that, the oldest become evicted. - There is a **ceiling of 20 terminal graphics contexts** at the same time. - The **hysteresis** — how long a card must be off screen before it is suspended — is on the order of a minute. - The **return** of a suspended card is limited per frame, and under critical memory pressure it is **postponed**: cards stay where they are instead of all coming back at once. > **These numbers are internal policy and may change between versions.** They are not a contract, and there is no way to configure them through the interface today. ## What you observe - **A card off screen comes back with its content.** The terminal buffer is preserved while the card is suspended or parked; on return, the screen is redrawn from it. - **There is no on-screen notice about suspending or evicting.** There is no "this card was suspended" indicator and no notification about it. Since it only happens to cards off screen, you normally do not notice. - **Minimizing is not closing.** A minimized card has its content kept, hidden, and keeps running. > **Mind a known defect.** A terminal may **come back black** after leaving the visible area or being minimized. If you find a black terminal when returning to a card, use **Reload** in the card's menu: it reattaches a new screen to the **same** process, and the work continues where it was. Do not close the card in that state — closing ends the session. ## What has been measured These measurements are from the project and serve to give an order of magnitude — they are **not** a performance promise on your machine: - **Before**: a board with many cards reached frames of up to **495 ms** in production while dragging the board. - **After staggering** (cards return in waves, not all in the same frame): the worst frame dropped to **139 ms**, and the fixed cost of around 100 ms per position update **remains open**. - **Opening a menu with 25 cards** dropped from 183 ms to 58 ms. - **Creating a note and being able to type in it** took **262 ms**. > **The project's yardstick is counting slow frames, not the average.** The target is 60 frames per second (33 ms per frame), and what is measured is **how many frames exceed 33 ms and 100 ms**. The average hides exactly what a person feels. ## About the instrumentation The Canvas has an internal **performance instrumentation**, reachable only through the application's developer window — **there is no product interface for it**. It measures renders, the time until the note editor accepts the first keystroke, and parking latencies, and it can be turned on without recompiling. If you are not the one touching the app's code, this changes nothing in your experience: it is a diagnostic tool. ## Limits worth knowing - **A large board is still a large board.** The limits reduce the cost, they do not remove the fact that every terminal is a process. - **Board state grows with use.** Every workspace keeps its layout, and that is not deleted on its own. - **No zoom-based LOD.** There is no "simplify the card when zoomed out" behavior today; cards are drawn as they are.