# dash-excalidraw — Excalidraw drawing canvas for Dash — full corpus ## Access policy - Terms: these documents are free to fetch. A free account unlocks any gated document. - Identity: agents may present a key by appending `?key=` to any document URL. Get one: https://2plot.ai - Rate: prefer ONE `/llms-full.txt` fetch over N per-page fetches. On 429, honour `Retry-After` and back off exponentially. - Coordination: start at https://2plot.dev/llms.txt — one index enumerates every site; do not rediscover the network by crawling it. - Crawler policy (mirrors /robots.txt): allowed: GPTBot, ClaudeBot, CCBot, Google-Extended, FacebookBot, Omgili, ByteSpider, Amazonbot, Applebot-Extended, meta-externalagent, AI2Bot, Diffbot, Timpibot, ImagesiftBot, ChatGPT-User, Claude-User, Claude-SearchBot, PerplexityBot, OAI-SearchBot, Perplexity-User, Googlebot, Bingbot, Slurp, DuckDuckBot, GoogleOther, Google-InspectionTool, Storebot-Google, AdsBot-Google. - Accounting: every document read is logged with the requesting vendor (verified against published IP ranges where the operator publishes them). See https://2plot.dev/llms.txt > dash-excalidraw — the Excalidraw whiteboard as a Dash component. JSON-safe props, imperative commands, event snapshots, AI scenes. By Pip Install Python. Generated from 21 pages. The page index lives at https://excalidraw.2plot.dev/llms.txt and a compact briefing at https://excalidraw.2plot.dev/llms-small.txt; each page also serves its own document at `/llms.txt`. --- # dash-excalidraw — Excalidraw drawing canvas for Dash > **`dash-excalidraw` — the [Excalidraw](https://excalidraw.com/) whiteboard as a first-class [Dash](https://dash.plotly.com/) component.** By [Pip Install Python](https://2plot.dev). Every canvas on this site is a running Dash app. Draw on them. ```bash pip install dash-excalidraw ``` --- ## The problem this solves Excalidraw is a React application with a large imperative API. Wrapping it for Dash means answering one question honestly: **what can cross the Python/JavaScript bridge?** Only JSON can. Functions, RegExps and class instances cannot. Most wrappers stop there and hand you a `clientside_callback` for anything interesting — which means writing JavaScript to use a Python component. This one translates the entire surface into three JSON-safe patterns, so you write ordinary `@callback`s and never touch JavaScript. | Upstream shape | What Python sees | Why | |---|---|---| | Callbacks (`onPaste`, `onPointerUpdate`, …) | **Snapshot props** — `lastPaste`, `lastPointerMove`, … each with a `timestamp` | A callback can't be serialized; a record of it firing can. The timestamp is how you dedupe. | | Imperative methods (`updateScene`, `exportToSvg`, …) | **`command`** — `{id, type, payload}`, dispatched once per unique `id` | One prop covers twelve methods, and a re-render can't re-fire a command. | | Async results | **`lastExport`**, carrying the `id` you dispatched | Exports resolve out of order under load. The id is how you correlate. | | `validateEmbeddable` RegExp | A **list of glob strings**, compiled to RegExps on the JS side | A RegExp has no JSON form. `"*.youtube.com"` does. | --- ## Thirty seconds to a canvas ```python from dash import Dash, Input, Output, callback, html from dash_excalidraw import DashExcalidraw app = Dash(__name__) app.layout = html.Div([ DashExcalidraw(id="canvas", height="600px"), html.Pre(id="count"), ]) @callback(Output("count", "children"), Input("canvas", "elements")) def show(elements): return f"{len(elements or [])} elements on the canvas" if __name__ == "__main__": app.run(debug=True) ``` Nothing else is required. The Excalidraw bundle, its stylesheet and its UI font ship inside the wheel as one self-contained JavaScript file — no CDN dependency at load time, no `external_stylesheets` entry, no build step. --- ## Where to go next **Start here** — [Basic usage](/basic) is the smallest useful app. [initialData](/initial-data) seeds a scene at mount. **Appearance** — [Theming](/theming), [View modes](/view-modes), [UIOptions](/ui-options). **Reading the canvas** — [Events](/events) shows every callback as a snapshot prop. [Persistence](/persistence) streams `serializedData` to a store and restores it. **Driving the canvas** — [Command dispatch](/commands) is the imperative API from Python. [Export](/export) is the async round-trip. [Library](/library) reads and writes the shape library. **At scale** — [File uploads](/file-uploads) keeps canvas JSON small by pushing pasted images to storage and swapping the base64 for URLs. [Collaboration](/collaboration) drives the collaborator UI and live cursors. **AI** — [AI agent](/ai-agent) turns a natural-language prompt into a scene, and is honest about what that costs. [Trace an image](/trace-image) redraws a picture as a scene, and [Scene viewer](/scene-viewer) renders any scene JSON — a trace included — with no model and no key. --- ## Excalidraw 0.18 Pinned exactly at 0.18.1, which brings elbow arrows, flowchart shortcuts, scene search, image cropping, element linking and the command palette — and patches the mermaid XSS advisory. One upgrade note worth reading before you dispatch a scene from Python: 0.18 replaced `commitToHistory` with `captureUpdate`, and **changed what the default means**. 0.17 left undo history untouched; 0.18 folds a programmatic push into the *next* captured action, so a user's first Ctrl+Z after your `updateScene` would also roll back their own previous edit. Nothing errors and nothing warns. This wrapper defaults to `IMMEDIATELY`, so a Python-dispatched push is one discrete, individually undoable step. [Command dispatch](/commands) covers the override. --- ## For agents Append `/llms.txt` to any URL on this site for the machine-readable Markdown of that page. The index is at [/llms.txt](/llms.txt), and every page document opens with a navigation block back to the site and network indexes rather than being a dead end. --- # AI agent > Turn a natural-language prompt into an Excalidraw scene with Claude, ChatGPT or Gemini, and what it costs. --- > **On this site these pages are documentation, not a hosted service.** > excalidraw.2plot.dev carries no provider keys, so generation is disabled > here and nothing below will spend anything. Everything on the page — > streaming onto the canvas, the cost estimate, the Stop button, the daily > spend ceiling — works when you run the repo locally with a `.env` holding a > provider key. This is deliberate and not a fault. ### Overview Turn a natural-language prompt into an Excalidraw scene. Pick a provider — Claude, ChatGPT or Gemini — write a prompt, hit generate; the result is dispatched to the canvas via `command: updateScene` (no component remount). Run the same prompt twice with different providers to compare output. Claude and ChatGPT runs **stream**: elements appear on the canvas as the model closes each one, so you watch the scene being drawn rather than waiting on a spinner and receiving it all at once. The status line counts shapes and seconds as they land. Gemini has no streaming path in its SDK, so it still returns the whole scene at the end — the page keeps that behaviour rather than faking progress it cannot see. Each provider is enabled only when its key is present, and the badges above the controls say which name was looked for. The cost line under the button prices the run **before** you click it: a typical figure and a ceiling, because the max-token budget bounds the spend without determining it. Gemini has no price on file here and says so rather than showing $0.00. ### Live demo ### Source ```python # File: docs/ai-agent/ai_agent.py """AI agent: turn a prompt into an Excalidraw scene via Claude, ChatGPT or Gemini. Uses the command dispatch pattern (`command: updateScene`) — no component remount, no key-hack needed on the canvas. The same page compares Claude Opus 4.7 / Sonnet 4.6 against GPT-6 Astra and Gemini 2.5 Flash / Pro. Ship-readiness checklist for using this in your own production app: 1. Set env vars: ANTHROPIC_API_KEY=... CHATGPT_API_KEY=... # OPENAI_API_KEY is accepted as a fallback GEMINI_API_KEY=... All three are optional — the page disables the corresponding provider if its key is missing, and says which name it looked for. 2. This page calls the LLM synchronously inside a Dash callback. For production-grade UX, wrap with a background task queue (Celery / RQ / Dramatiq) or Dash's `background=True` long-callback machinery. The code here prioritizes clarity over throughput. 3. The prompt template is a starting point — tune `SYSTEM_PROMPT` for your domain. Prompt caching is active on Claude calls because the system prompt is stable across requests. """ from __future__ import annotations import json import os import re import time import traceback import uuid from typing import Any, Dict import dash import dash_mantine_components as dmc from dash import Input, Output, State, callback, clientside_callback, dcc, html, no_update from dash_excalidraw import DashExcalidraw from lib import scene_library, scene_stream, spend from lib.scene_ai import ( # shared with /benchmark — see lib/scene_ai.py CLAUDE_EFFORT, CLAUDE_MAX_TOKENS, CLAUDE_MODELS, MODEL_PRICING, EFFORT_CAPABLE, EFFORT_LEVELS, NO_KEYS_NOTICE, MODEL_EFFORT, MODEL_MAX_TOKENS, OPENAI_MODELS, any_provider_configured, available_models, call_model, estimate_cost, format_money, supported_efforts, GEMINI_MAX_TOKENS, GEMINI_MODELS, SYSTEM_PROMPT, _call_gemini, _cleanup_json, _coerce_types, _extract_json_block, _parse_and_normalize, _spend_allowed, ) from docs._shared import canvas_frame, sync_canvas_theme sync_canvas_theme("ai-canvas") def offered_claude_models(): """The models this deployment's key can actually call. CALLED FROM A CALLBACK, NEVER AT IMPORT. Page modules are imported while Dash registers pages, so a module-level call here put an outbound request to api.anthropic.com on the BOOT path — every start of the app blocked on a third party being reachable, and the answer was then frozen for the life of the process. It was visible in the boot log, one line under "Loading docs/ai-agent/ai-agent.md": INFO:httpx:HTTP Request: GET https://api.anthropic.com/v1/models... `available_models` caches, so calling it per callback costs one request for the process and no more. `verified` False means the check could not run — the full table is offered and the page SAYS so rather than implying it was checked. """ return available_models(CLAUDE_MODELS) # --------------------------------------------------------------------------- # Prompt template (domain-specific instructions for producing Excalidraw JSON) # --------------------------------------------------------------------------- # Read once at import: on the deployed site this never changes, and locally a # `.env` edit means a restart anyway. ANY_KEY = any_provider_configured() HAS_CLAUDE_KEY = bool(os.environ.get("ANTHROPIC_API_KEY")) # CHATGPT_API_KEY is this site's name; OPENAI_API_KEY is the SDK's own and is # accepted so a machine that already exports one needs no second copy. HAS_CHATGPT_KEY = bool(os.environ.get("CHATGPT_API_KEY")) or bool( os.environ.get("OPENAI_API_KEY") ) HAS_GEMINI_KEY = bool(os.environ.get("GEMINI_API_KEY")) or bool( os.environ.get("GOOGLE_API_KEY") ) # --------------------------------------------------------------------------- # Providers # --------------------------------------------------------------------------- def _benchmark_status(provider, model, element_count, elapsed, meta) -> str: """One line carrying everything a sweep needs to be compared. Elements alone say nothing about whether a setting was worth it — the interesting question is elements per second and per dollar, at a given effort and budget. So the line reports the settings ACTUALLY applied (which is not always what was asked: effort is silently dropped on models that reject it) alongside tokens, latency and an estimated cost. """ plural = "s" if element_count != 1 else "" head = f"{model} — {element_count} element{plural} in {elapsed:.0f}s" if not meta: return f"Generated via {provider} / {head}." bits = [f"effort={meta['effort']}", f"max_tokens={meta['max_tokens']:,}"] if meta.get("effort_ignored"): bits.append("(effort ignored — model rejects it)") out_tok, in_tok = meta["output_tokens"], meta["input_tokens"] bits.append(f"{out_tok:,} out / {in_tok:,} in") if meta.get("cache_read"): bits.append(f"{meta['cache_read']:,} cached") # MODEL_PRICING, not CLAUDE_PRICING: a ChatGPT run priced from the Claude # table finds nothing and silently reports no cost at all, which reads as # "this was free". price = MODEL_PRICING.get(model) if price and (out_tok or in_tok): cost = (in_tok * price[0] + out_tok * price[1]) / 1_000_000 # Estimate, not a bill — see CLAUDE_PRICING. bits.append(f"~${cost:.3f}") if element_count: bits.append(f"{elapsed / element_count:.1f}s/element") # Say truncation in words. `stop=max_tokens` is accurate and means nothing # to someone whose scene just stopped growing — and hitting the budget is # the single most common reason a drawing comes out shorter than asked # for, because the budget covers thinking AND output. stop = meta.get("stop_reason") if stop in ("max_tokens", "incomplete"): bits.append( f"TRUNCATED — hit the {meta['max_tokens']:,}-token budget; " f"raise it or lower effort for a longer scene" ) elif stop and stop not in ("end_turn", "completed"): bits.append(f"stop={stop}") return f"{head} · " + " · ".join(bits) def _format_parse_error(raw: str, exc: json.JSONDecodeError) -> str: """Show a window of text around the failure position so the Parsed tab actually helps you understand what broke.""" pos = exc.pos or 0 start = max(0, pos - 120) end = min(len(raw), pos + 120) pointer = " " * (pos - start) + "^" return ( f"JSON parse error: {exc.msg}\n" f" at line {exc.lineno}, column {exc.colno} (char {pos})\n\n" f"--- context (±120 chars) ---\n" f"{raw[start:end]}\n" f"{pointer}\n" f"--- end context ---\n\n" f"Length of model response: {len(raw)} chars.\n" f"Try switching to a different model, shortening your prompt, or " f"asking for a simpler diagram." ) # --------------------------------------------------------------------------- # Layout # --------------------------------------------------------------------------- def _provider_status(): if not ANY_KEY: # ONE neutral notice, not three red badges. This is the permanent # state of the deployed site, so it has to read as "this is how the # page is here", not as a fault. Red would be a lie: nothing is # broken and nothing the reader can do would fix it. return dmc.Alert( NO_KEYS_NOTICE, title="AI generation is disabled on this site", color="blue", variant="light", ) items = [] items.append( dmc.Badge( "Claude: ready" if HAS_CLAUDE_KEY else "Claude: missing ANTHROPIC_API_KEY", color="green" if HAS_CLAUDE_KEY else "red", variant="light", size="sm", ) ) items.append( dmc.Badge( "ChatGPT: ready" if HAS_CHATGPT_KEY else "ChatGPT: missing CHATGPT_API_KEY", color="green" if HAS_CHATGPT_KEY else "red", variant="light", size="sm", ) ) items.append( dmc.Badge( "Gemini: ready" if HAS_GEMINI_KEY else "Gemini: missing GEMINI_API_KEY", color="green" if HAS_GEMINI_KEY else "red", variant="light", size="sm", ) ) # The "unverified" badge cannot be decided here: knowing whether the # model list was checked means asking the provider, and this function runs # at page-import time. The slot is filled by `_sync_models` on first # render instead. items.append(html.Div(id="ai-model-check")) return dmc.Group(items, gap="xs") component = dmc.Stack( gap="md", children=[ _provider_status(), dmc.Paper( withBorder=True, p="md", children=dmc.Stack( gap="sm", children=[ dmc.Grid( gutter="md", children=[ dmc.GridCol( dmc.Select( id="ai-provider", label="Provider", data=[ {"value": "claude", "label": "Claude"}, {"value": "chatgpt", "label": "ChatGPT"}, {"value": "gemini", "label": "Gemini"}, ], # Land on a provider whose key is present, # so the first click can succeed. Falls # back to Claude, which then reports the # missing key by name. value=( "claude" if HAS_CLAUDE_KEY else "chatgpt" if HAS_CHATGPT_KEY else "gemini" if HAS_GEMINI_KEY else "claude" ), ), span={"base": 12, "sm": 3}, ), dmc.GridCol( dmc.Select( id="ai-model", label="Model", # Filled by `_sync_models` on first # render — see offered_claude_models(). data=[], value=None, ), span={"base": 12, "sm": 4}, ), dmc.GridCol( dmc.Select( id="ai-effort", label="Effort", description="Thinking depth", data=EFFORT_LEVELS, value=CLAUDE_EFFORT.get( CLAUDE_MODELS[0]["value"] ) or "low", ), span={"base": 6, "sm": 2}, ), dmc.GridCol( dmc.NumberInput( id="ai-max-tokens", label="Max tokens", description="Caps thinking + output together", value=CLAUDE_MAX_TOKENS[ CLAUDE_MODELS[0]["value"] ], min=1000, max=128000, step=4000, ), span={"base": 6, "sm": 2}, ), dmc.GridCol( dmc.NumberInput( id="ai-seed", label="Seed", description="Bump for a fresh id namespace", value=1, min=1, ), span={"base": 12, "sm": 1}, ), ], ), # What this run will cost, BEFORE it is triggered. The # three controls above are all cost levers and none of # them says so on its own — model sets the rate, max # tokens sets the ceiling, effort sets how much of that # ceiling gets used. dmc.Alert( id="ai-estimate", color="gray", variant="light", p="xs", ), dmc.Textarea( id="ai-prompt", label="Prompt", placeholder="E.g. 'a flowchart for onboarding a new engineer: signup → security training → first PR → mentorship pairing'", autosize=True, minRows=3, maxRows=6, ), dmc.Group( [ dmc.Button( "Generate", id="ai-generate-btn", leftSection="✨", color="indigo", loaderProps={"type": "dots"}, # Nothing to generate with, so the control is # off rather than offering a click that can # only produce an error. disabled=not ANY_KEY, ), # THE BRAKES. Enabled only while a run is in # flight, and filled (not subtle) because the # moment you want it is the moment you should not # have to hunt for it. dmc.Button( "Stop", id="ai-stop-btn", leftSection="■", color="red", disabled=True, ), dmc.Button( "Clear canvas", id="ai-clear-btn", variant="subtle", color="red", ), # The scene library: LOCAL-ONLY, enabled on the same # condition as generation itself (provider keys # present). See lib/scene_library.py. dmc.Button( "Save scene", id="ai-save-btn", leftSection="💾", variant="light", color="indigo", disabled=not ANY_KEY, ), dmc.Select( id="ai-library", placeholder=( "Saved scenes (local)" if ANY_KEY else "Scene library is local-only" ), data=[], searchable=True, clearable=True, w=380, disabled=not ANY_KEY, ), ] ), ], ), ), # Processing banner — driven by the callback's `running=` clause so # feedback appears the instant the click registers, not once the # model has returned. `running` collides with normal Outputs, so # this element is only *shown*/*hidden* from running; its inner # copy is static. html.Div( id="ai-processing-banner", style={"display": "none"}, children=dmc.Alert( color="blue", variant="light", children=dmc.Group( gap="sm", children=[ dmc.Loader(size="sm", color="blue", type="bars"), dmc.Stack( gap=0, children=[ dmc.Text( "Generating scene…", fw=600, size="sm", ), dmc.Text( "Sending prompt to the model and parsing " "the response — typically 2–20 s. Opus / " "Gemini Pro are slower than Sonnet / Flash.", size="xs", c="dimmed", ), ], ), ], ), ), ), dmc.Alert( id="ai-status", children="Ready.", color="gray", variant="light", title="Status", ), dcc.Store(id="ai-last-raw", data=""), # The drawing in ARRIVAL ORDER, captured from the canvas command stream # (see the timeline section at the bottom). The timeline replays # `elements[:i]`. dcc.Store(id="ai-history", data={"elements": []}), # Mirror of this page's controls for window.DeckBridge (assets/ # deck_bridge.js) — how a Stream Deck drives this page. Holds only a # timestamp; the state itself lives on window. dcc.Store(id="ai-deck-mirror"), dcc.Store(id="ai-library-mount", data=0), # The streaming pair. `ai-run` holds the id of the generation in # flight plus how many elements the canvas has already been shown; # `ai-stream-tick` collects whatever arrived since. 400ms is fast # enough that shapes appear to land as they are drawn, and slow # enough that a long generation is a few dozen polls rather than a # few thousand. dcc.Store(id="ai-run", data=None), dcc.Interval(id="ai-stream-tick", interval=400, disabled=True), dmc.Tabs( value="canvas", children=[ dmc.TabsList( [ dmc.TabsTab("Canvas", value="canvas"), dmc.TabsTab("Raw response", value="raw"), dmc.TabsTab("Parsed envelope", value="parsed"), ] ), dmc.TabsPanel( value="canvas", pt="sm", children=dmc.Box( style={"position": "relative"}, children=[ dmc.LoadingOverlay( id="ai-canvas-overlay", visible=False, zIndex=100, overlayProps={ "radius": "md", "blur": 2, "backgroundOpacity": 0.55, }, loaderProps={ "color": "indigo", "type": "bars", "size": "lg", }, ), canvas_frame( DashExcalidraw( id="ai-canvas", height="640px", UIOptions={ "welcomeScreen": False, "canvasActions": { "clearCanvas": True, "export": False, "saveAsImage": True, }, }, ), min_height=640, ), # THE TIMELINE. Every scene arrives one element at a # time, so the draw order is a timeline for free: # scrub it to step back through the drawing, or # replay it. Works on saved scenes too. dmc.Paper( withBorder=True, p="sm", mt="xs", children=dmc.Stack( gap=6, children=[ dmc.Group( [ dmc.Button( "Replay", id="ai-timeline-play", leftSection="▶", size="xs", variant="light", color="indigo", ), dmc.Text("Timeline", size="sm", fw=600), dmc.Text( "No scene yet.", id="ai-timeline-label", size="xs", c="dimmed", ), ], gap="sm", ), dmc.Slider( id="ai-timeline", min=0, max=1, value=0, step=1, disabled=True, color="indigo", ), ], ), ), ], ), ), dmc.TabsPanel( value="raw", pt="sm", children=dcc.Loading( id="ai-raw-loading", type="default", delay_show=200, delay_hide=300, custom_spinner=dmc.Stack( gap="xs", p="sm", children=[ dmc.Skeleton(height=18, width="40%", radius="sm"), dmc.Skeleton(height=14, radius="sm"), dmc.Skeleton(height=14, width="95%", radius="sm"), dmc.Skeleton(height=14, width="80%", radius="sm"), dmc.Skeleton(height=14, width="90%", radius="sm"), dmc.Skeleton(height=14, width="70%", radius="sm"), dmc.Skeleton(height=14, radius="sm"), dmc.Skeleton(height=14, width="60%", radius="sm"), ], ), children=dmc.ScrollArea( style={"height": 520}, children=dmc.Code( id="ai-raw", block=True, style={ "whiteSpace": "pre-wrap", "wordBreak": "break-word", "fontSize": 11, }, ), ), ), ), dmc.TabsPanel( value="parsed", pt="sm", children=dcc.Loading( id="ai-parsed-loading", type="default", delay_show=200, delay_hide=300, custom_spinner=dmc.Stack( gap="xs", p="sm", children=[ dmc.Skeleton(height=18, width="35%", radius="sm"), dmc.Skeleton(height=14, radius="sm"), dmc.Skeleton(height=14, width="88%", radius="sm"), dmc.Skeleton(height=14, width="92%", radius="sm"), dmc.Skeleton(height=14, width="75%", radius="sm"), dmc.Skeleton(height=14, radius="sm"), dmc.Skeleton(height=14, width="65%", radius="sm"), ], ), children=dmc.ScrollArea( style={"height": 520}, children=dmc.Code( id="ai-parsed", block=True, style={ "whiteSpace": "pre-wrap", "wordBreak": "break-word", "fontSize": 11, }, ), ), ), ), ], ), ], ) # --------------------------------------------------------------------------- # Callbacks # --------------------------------------------------------------------------- @callback( Output("ai-estimate", "children"), Output("ai-estimate", "color"), Input("ai-provider", "value"), Input("ai-model", "value"), Input("ai-effort", "value"), Input("ai-max-tokens", "value"), ) def _show_estimate(provider, model, effort, max_tokens): """Price this run before it happens. Two numbers, not one, and the reason is in `estimate_cost`: `max_tokens` is a ceiling, so a single figure has to choose between being pessimistic (quote the ceiling, and every real run looks like a bargain) or optimistic (quote the typical, and the bill can exceed the quote). Showing both makes the spread itself the information — it is exactly what effort controls. """ if not ANY_KEY: return ( "No provider keys on this site — nothing is spent here. " "The estimate works locally with a `.env`.", "blue", ) if not model: # First paint: the model control ships empty and `_sync_models` fills # it. Without this the estimate would flash "no price on file for # this model", which reads as a broken model rather than an unfinished # render. return "Checking which models this key can call…", "gray" if provider == "gemini": # Gemini has no entry in MODEL_PRICING and its billing is not ours to # quote. Saying so beats rendering $0.00, which reads as "free". return "No cost estimate for Gemini here — see Google's pricing.", "gray" est = estimate_cost(model, effort, max_tokens) if not est["priced"]: if est["reason"] == "budget": # Mid-edit the NumberInput hands over whatever is in the box, so # this is a normal transient state, not an error worth shouting # about. It used to raise here and 500 the callback. return "Set a max-token budget to see the cost.", "gray" return "No price on file for this model — cost unknown.", "gray" # The budget AS PRICED, not the raw control value — they differ whenever # the box holds something like "64.000" or a number outside the range. budget = est["budget"] sent = est["effort"] effort_phrase = ( f"effort {sent}" if sent else "no effort set (the model's own default)" ) budget_state = spend.summary() parts = [ dmc.Text( [ "About ", dmc.Text(format_money(est["typical"]), fw=700, span=True), f" for this run · at most {format_money(est['ceiling'])} " f"if it uses the whole budget.", ], size="sm", ), dmc.Text( f"{budget:,} max tokens · {effort_phrase} · " f"typical run uses ~{est['fraction']:.0%} of the budget.", size="xs", c="dimmed", ), ] # What is left today. Shown always rather than only when low: a number # that appears for the first time when you are nearly out is a number # nobody has learned to read. parts.append( dmc.Text( f"Daily budget: {format_money(budget_state['spent'])} of " f"{format_money(budget_state['ceiling'])} used · " f"{format_money(budget_state['remaining'])} left (resets midnight UTC).", size="xs", c="orange" if budget_state["fraction"] > 0.8 else "dimmed", ) ) # Say it out loud when the level in the selector is not the level that # will be sent — otherwise the estimate looks wrong rather than the # control looking inert. if effort and effort != "none" and sent is None: parts.append( dmc.Text( f"This model ignores the effort parameter, so “{effort}” " f"costs the same as any other level here.", size="xs", c="dimmed", fs="italic", ) ) return dmc.Stack(parts, gap=2), "gray" # Clear stays SYNCHRONOUS and is its own callback. It is instant, and routing # it through a job queue would add a round trip to a button whose whole value # is that it responds immediately. Splitting it also keeps `ctx.triggered_id` # out of the background worker, where callback context is a different animal. # # It writes the same Output as the generator, so one of the two must declare # allow_duplicate — this one, because it is the secondary writer. @callback( Output("ai-model", "data"), Output("ai-model", "value"), Output("ai-model-check", "children"), Input("ai-provider", "value"), prevent_initial_call=False, ) def _sync_models(provider): """Fill the model list, and say whether it was verified. `prevent_initial_call=False` is load-bearing: this fires on first render, which is what lets the control ship empty and the availability check stay off the import path. """ if provider == "chatgpt": return OPENAI_MODELS, OPENAI_MODELS[0]["value"], None if provider == "gemini": return GEMINI_MODELS, GEMINI_MODELS[0]["value"], None data, verified = offered_claude_models() # With no key at all, "unverified" is noise: of course it could not be # checked, and the notice above already says why. The badge is for the # case where a key EXISTS and the check still could not run. badge = ( None if verified or not ANY_KEY else dmc.Badge( "model list unverified", color="yellow", variant="light", size="sm" ) ) return data, data[0]["value"], badge @callback( Output("ai-effort", "value"), Output("ai-effort", "data"), Output("ai-max-tokens", "value"), Output("ai-effort", "disabled", allow_duplicate=True), Input("ai-model", "value"), prevent_initial_call=True, ) def _sync_model_defaults(model): """Move effort and budget to this model's defaults when the model changes. Without this, switching models silently carries the previous model's settings over — which quietly invalidates a comparison, because you would be reading a difference between models that is partly a difference in configuration. The effort control is also disabled outright on models that reject the parameter, so the UI cannot offer a choice the API will 400 on. """ capable = model in EFFORT_CAPABLE allowed = set(supported_efforts(model)) data = [e for e in EFFORT_LEVELS if e["value"] in allowed] # MODEL_* rather than CLAUDE_*: switching to a ChatGPT model has to pick # up ITS defaults, or the run would carry the previous provider's budget # and the comparison would be measuring configuration, not models. effort = (MODEL_EFFORT.get(model) or "none") if capable else "none" if effort not in allowed: effort = "none" return effort, data, MODEL_MAX_TOKENS.get(model, 32000), not capable # Clear stays SYNCHRONOUS and is its own callback. It is instant, and routing # it through a job queue would add a round trip to a button whose whole value # is that it responds immediately. Splitting it also keeps `ctx.triggered_id` # out of the background worker, where callback context is a different animal. # # It writes the same Output as the generator, so one of the two must declare # allow_duplicate — this one, because it is the secondary writer. @callback( Output("ai-canvas", "command", allow_duplicate=True), Output("ai-status", "children", allow_duplicate=True), Output("ai-status", "color", allow_duplicate=True), Output("ai-raw", "children", allow_duplicate=True), Output("ai-parsed", "children", allow_duplicate=True), Output("ai-last-raw", "data", allow_duplicate=True), Input("ai-clear-btn", "n_clicks"), prevent_initial_call=True, ) def _clear(_clicks): cmd = { "id": f"clear-{uuid.uuid4()}", "type": "updateScene", "payload": {"elements": []}, } return cmd, "Canvas cleared.", "gray", "", "", "" @callback( Output("ai-canvas", "command"), Output("ai-status", "children"), Output("ai-status", "color"), Output("ai-raw", "children"), Output("ai-parsed", "children"), Output("ai-last-raw", "data"), Output("ai-run", "data"), Output("ai-stream-tick", "disabled"), Input("ai-generate-btn", "n_clicks"), State("ai-provider", "value"), State("ai-model", "value"), State("ai-effort", "value"), State("ai-max-tokens", "value"), State("ai-prompt", "value"), running=[ # ONLY the banner. The canvas overlay used to be here and is gone on # purpose: it covered the canvas for the whole call, which is the # exact thing streaming exists to remove. Everything else that needs # locking is handled by `_lock_controls`, which keys off the ticker # and therefore stays on for the whole DRAWING, not just this # callback — which now returns in milliseconds. ( Output("ai-processing-banner", "style"), {"display": "block", "marginTop": 4, "marginBottom": 4}, {"display": "none"}, ), ], prevent_initial_call=True, ) def _generate(_gen_clicks, provider, model, effort, max_tokens, prompt): """START a generation. Returns immediately; the canvas fills in as it draws. This used to block for the whole call and hand back a finished scene, which is why the page had a loading overlay: there was nothing to show until there was everything to show. Claude and ChatGPT runs now go to a worker thread that parses elements out of the token stream as each one closes, and `ai-stream-tick` collects them — first shape on the canvas in a few seconds instead of a minute of spinner. `background=` is gone with the blocking call. It existed so a 100-second generation could not hold a request worker and take /healthz down with it; the generation no longer happens in a callback at all, so the risk it guarded against is gone with it. The producer is a plain thread — see lib/scene_stream.start for why not a background worker. Gemini still runs synchronously: `_call_gemini` has no streaming path and returns a whole string, so there is nothing to stream. It keeps the old behaviour rather than pretending otherwise. """ idle = (no_update,) * 6 + (no_update, True) # The button is disabled, so this is only reachable by a crafted request. # Answered in the same words and the same colour as the notice above, # because a caller who gets here has not done anything wrong either. if not ANY_KEY: return (no_update, NO_KEYS_NOTICE, "blue") + idle[3:] if not prompt or not prompt.strip(): return (no_update, "Write a prompt first.", "yellow") + idle[3:] # ---- THE SPEND GATE ------------------------------------------------- # This check has to live HERE, not on the page's `tier: auth`, and the # reason is worth stating because the frontmatter looks like it covers it. # # 1. `lib/page_tiers.degraded_tier` makes every tier except `hidden` fail # OPEN when Clerk is not configured. That is the right trade for # reading documentation and exactly the wrong one for a page that # spends money, which must fail CLOSED. # 2. Page tiers are path-based, and every Dash callback posts to the one # shared `/_dash-update-component` route. No path-based gate can tell # this callback from any other. # # So the page tier governs who can READ the page; this governs who can # make it BILL. if not _spend_allowed(): return ( no_update, "Sign in to generate — this page spends real API credits, so " "generation is limited to signed-in visitors.", "yellow", ) + idle[3:] missing = { "claude": (not HAS_CLAUDE_KEY, "ANTHROPIC_API_KEY is not set in the environment."), "chatgpt": ( not HAS_CHATGPT_KEY, "CHATGPT_API_KEY / OPENAI_API_KEY is not set in the environment.", ), "gemini": ( not HAS_GEMINI_KEY, "GEMINI_API_KEY / GOOGLE_API_KEY is not set in the environment.", ), }.get(provider, (False, "")) if missing[0]: return (no_update, missing[1], "red") + idle[3:] # The ceiling, checked HERE as well as inside the call. `stream_model` # admits once per run, but it is a generator whose body does not execute # until the worker thread advances it — so without this the refusal would # arrive as a red error on a run that had already been created. Checking # up front makes a blown budget a clean, yellow "not now". try: spend.check(estimate_cost(model, effort, max_tokens)["typical"]) except spend.CeilingReached as exc: return (no_update, str(exc), "yellow") + idle[3:] # ---- Gemini: no stream available, so keep the one-shot path ------------ if provider == "gemini": started = time.monotonic() try: raw = _call_gemini(model, prompt.strip()) except Exception as exc: # noqa: BLE001 - surface any provider error traceback.print_exc() return (no_update, f"{provider} call failed: {exc}", "red", str(exc), "", "", no_update, True) try: parsed = _parse_and_normalize(raw) except json.JSONDecodeError as exc: return ( no_update, f"Parse error at char {exc.pos}: {exc.msg}. See Parsed tab for context.", "red", raw, _format_parse_error(raw, exc), raw, no_update, True, ) except ValueError as exc: return (no_update, f"Parse error: {exc}", "red", raw, str(exc), raw, no_update, True) elements = parsed.get("elements", []) cmd = { "id": f"ai-{uuid.uuid4()}", "type": "updateScene", "payload": { "elements": elements, "appState": parsed.get("appState", {}), "files": parsed.get("files", {}), }, } status = _benchmark_status( provider, model, len(elements), time.monotonic() - started, None ) return (cmd, status, "green", raw, json.dumps(parsed, indent=2), raw, no_update, True) # ---- Claude / ChatGPT: stream it -------------------------------------- try: run_id = scene_stream.start( model=model, user_prompt=prompt.strip(), max_tokens=max_tokens, effort=effort, ) except Exception as exc: # noqa: BLE001 - a bad model id, a missing key traceback.print_exc() return (no_update, f"{type(exc).__name__}: {exc}", "red") + idle[3:] # Blank the canvas so the drawing starts from nothing and each shape's # arrival is visible, rather than accumulating over the previous scene. return ( {"id": f"ai-reset-{run_id[:8]}", "type": "resetScene", "payload": {}}, "Drawing…", "gray", no_update, no_update, no_update, {"id": run_id, "cursor": 0, "provider": provider, "model": model}, False, ) @callback( Output("ai-canvas", "command", allow_duplicate=True), Output("ai-status", "children", allow_duplicate=True), Output("ai-status", "color", allow_duplicate=True), Output("ai-raw", "children", allow_duplicate=True), Output("ai-parsed", "children", allow_duplicate=True), Output("ai-last-raw", "data", allow_duplicate=True), Output("ai-run", "data", allow_duplicate=True), Output("ai-stream-tick", "disabled", allow_duplicate=True), Input("ai-stream-tick", "n_intervals"), State("ai-run", "data"), prevent_initial_call=True, ) def _stream_tick(_n, run): """Collect whatever the worker has parsed since the last poll.""" stop = (no_update,) * 7 + (True,) if not run or not run.get("id"): return stop state = scene_stream.take(run["id"], run.get("cursor", 0)) if not state["found"]: # Expired, forgotten, or an instance restart took the store with it. # Stop polling rather than ask forever about a run that cannot answer. return stop elements = state["all"] run_next = {**run, "cursor": state["cursor"]} if state["error"]: scene_stream.forget(run["id"]) return (no_update, state["error"], "red", no_update, no_update, no_update, None, True) # updateScene REPLACES the scene, so every tick sends everything so far. # captureUpdate NEVER while drawing: without it each tick becomes its own # undo step, and a 40-element scene would take 40 Ctrl+Z to undo. cmd = no_update if state["elements"]: cmd = { "id": f"ai-tick-{run['id'][:8]}-{state['cursor']}", "type": "updateScene", "payload": {"elements": elements, "captureUpdate": "NEVER"}, } # A gap means elements the producer wrote can no longer be read back, so # the canvas is missing shapes it was already shown. Saying nothing is how # this last went unnoticed for a whole session — it just looked like the # model drawing less. lost_note = f" · {state['lost']} lost from the buffer" if state.get("lost") else "" if not state["done"]: plural = "s" if len(elements) != 1 else "" return ( cmd, f"Drawing… {len(elements)} element{plural} so far " f"({state['elapsed']:.0f}s){lost_note}", "orange" if state.get("lost") else "gray", no_update, no_update, no_update, run_next, False, ) scene_stream.forget(run["id"]) if not elements: return ( no_update, "The model returned no elements. Try a different model or a " "larger budget.", "yellow", no_update, no_update, no_update, None, True, ) # One last updateScene, this time as a single undoable step. final_cmd = { "id": f"ai-final-{run['id'][:8]}", "type": "updateScene", "payload": {"elements": elements, "captureUpdate": "IMMEDIATELY"}, } # The Raw tab shows the scene REBUILT from the streamed elements rather # than the exact bytes off the wire: the parser consumes the deltas as # they arrive, and keeping a second full copy of every response in memory # to populate a tab is not worth the memory. rebuilt = json.dumps({"elements": elements}, indent=2) status = _benchmark_status( run.get("provider"), run.get("model"), len(elements), state["elapsed"], state["meta"], ) if state.get("lost"): status = ( f"{status} · WARNING: {state['lost']} element(s) were generated " f"but could not be read back, so this scene is incomplete." ) return final_cmd, status, "orange", rebuilt, rebuilt, rebuilt, None, True return final_cmd, status, "green", rebuilt, rebuilt, rebuilt, None, True @callback( Output("ai-status", "children", allow_duplicate=True), Output("ai-status", "color", allow_duplicate=True), Output("ai-run", "data", allow_duplicate=True), Output("ai-stream-tick", "disabled", allow_duplicate=True), Input("ai-stop-btn", "n_clicks"), State("ai-run", "data"), prevent_initial_call=True, ) def _stop(_clicks, run): """Press the brakes: stop the generation, keep what it has drawn. Two things have to happen and only one of them is obvious. Disabling the ticker stops the PAGE from polling — but the worker thread would carry on pulling tokens to the full budget with nobody reading them, which is exactly the cost this button exists to prevent. `scene_stream.cancel` closes the provider stream, so billing stops at the tokens already produced. What is on the canvas stays there. A stop is not an undo: the shapes drawn so far are usually the reason you are stopping. """ if not run or not run.get("id"): return no_update, no_update, no_update, True scene_stream.cancel(run["id"]) drawn = len(scene_stream.take(run["id"], 0)["all"]) plural = "s" if drawn != 1 else "" return ( f"Stopped. {drawn} element{plural} kept; no further tokens are being " f"generated.", "yellow", None, True, ) @callback( Output("ai-generate-btn", "loading"), Output("ai-generate-btn", "disabled"), Output("ai-stop-btn", "disabled"), Output("ai-clear-btn", "disabled"), Output("ai-prompt", "disabled"), Output("ai-provider", "disabled"), Output("ai-model", "disabled"), Output("ai-max-tokens", "disabled"), Input("ai-stream-tick", "disabled"), ) def _lock_controls(tick_disabled): """Lock the controls while a drawing is in flight. Keyed on the TICKER, not on the generate callback's lifetime: that callback now returns in milliseconds, so a `running=` lock would release while the canvas was still filling in. The ticker being enabled is the definition of "a run is in progress". """ drawing = not tick_disabled # `or not ANY_KEY`: with no provider configured these stay off for good. # Without it this callback would re-enable the button on first render and # hand the reader a click whose only outcome is a red error. off = drawing or not ANY_KEY # Stop is the one control that is enabled precisely when a run is going. return (drawing, off, not drawing) + (off,) * 5 # --------------------------------------------------------------------------- # Timeline, scene library, and the Stream Deck bridge # --------------------------------------------------------------------------- # # The timeline is CLIENTSIDE end to end. The history is captured from the # canvas `command` prop itself — every updateScene the stream sends carries # all elements so far, in arrival order — so none of the streaming callbacks # above had to change. Scrubbing writes the canvas through # `dash_clientside.set_props` rather than an Output: an Output on # `ai-canvas.command` from a callback that (indirectly) listens to it would be # a dependency cycle, and set_props is outside the static graph. Commands the # timeline itself sends carry a `tl-` id prefix and are ignored by the capture. clientside_callback( """ function (cmd) { var nu = window.dash_clientside.no_update; if (!cmd || !cmd.type) return nu; if (String(cmd.id || "").indexOf("tl-") === 0) return nu; if (cmd.type === "resetScene") return {elements: [], t: Date.now()}; if (cmd.type === "updateScene" && cmd.payload && Array.isArray(cmd.payload.elements)) { return {elements: cmd.payload.elements, t: Date.now()}; } return nu; } """, Output("ai-history", "data"), Input("ai-canvas", "command"), prevent_initial_call=True, ) clientside_callback( """ function (h) { var n = ((h && h.elements) || []).length; window.__aiTlShown = n; // the canvas already shows the whole scene return [Math.max(n, 1), n, n === 0, n ? (n + " / " + n + " elements") : "No scene yet."]; } """, Output("ai-timeline", "max"), Output("ai-timeline", "value"), Output("ai-timeline", "disabled"), Output("ai-timeline-label", "children"), Input("ai-history", "data"), prevent_initial_call=True, ) clientside_callback( """ function (v, h, tickDisabled) { var nu = window.dash_clientside.no_update; var els = (h && h.elements) || []; if (v === null || v === undefined || !els.length) return nu; var label = v + " / " + els.length + " elements"; if (v === window.__aiTlShown) return label; if (tickDisabled === false) return label + " — drawing; scrub when it finishes"; window.__aiTlShown = v; window.dash_clientside.set_props("ai-canvas", {command: { id: "tl-" + Date.now() + "-" + v, type: "updateScene", payload: {elements: els.slice(0, v), captureUpdate: "NEVER"} }}); return label; } """, Output("ai-timeline-label", "children", allow_duplicate=True), Input("ai-timeline", "value"), State("ai-history", "data"), State("ai-stream-tick", "disabled"), prevent_initial_call=True, ) clientside_callback( """ function (n, h) { var nu = window.dash_clientside.no_update; var N = ((h && h.elements) || []).length; if (!n || !N) return nu; if (window.__aiTlTimer) clearInterval(window.__aiTlTimer); var i = 0, ms = Math.max(40, Math.min(250, 6000 / N)); window.dash_clientside.set_props("ai-timeline", {value: 0}); window.__aiTlTimer = setInterval(function () { i += 1; window.dash_clientside.set_props("ai-timeline", {value: i}); if (i >= N) { clearInterval(window.__aiTlTimer); window.__aiTlTimer = null; } }, ms); return nu; } """, Output("ai-timeline-play", "loading"), Input("ai-timeline-play", "n_clicks"), State("ai-history", "data"), prevent_initial_call=True, ) # The deck mirror. Publishes this page's controls to window.DeckBridge on every # change; the deck reads them back with one JS call and writes through # set_props, so provider → model → defaults chains run exactly as by hand. # Page actions (generate, preset, …) live in assets/deck_bridge_ai_agent.js. clientside_callback( """ function (prov, mdata, mval, edata, effort, edis, mt, seed, tl, hist, ldata, lval, tickDisabled, status, pdata) { if (!window.DeckBridge) return window.dash_clientside.no_update; var drawing = tickDisabled === false; var n = ((hist && hist.elements) || []).length; return window.DeckBridge.update(location.pathname, { provider: {type: "select", id: "ai-provider", value: prov, options: pdata, wrap: true, disabled: drawing}, model: {type: "select", id: "ai-model", value: mval, options: mdata, wrap: true, disabled: drawing}, effort: {type: "select", id: "ai-effort", value: effort, options: edata, disabled: !!edis || drawing}, max_tokens: {type: "number", id: "ai-max-tokens", value: mt, min: 1000, max: 128000, step: 4000, label: (mt || 0).toLocaleString(), disabled: drawing}, seed: {type: "number", id: "ai-seed", value: seed, min: 1, max: 9999, step: 1}, timeline: {type: "number", id: "ai-timeline", value: tl, min: 0, max: n, step: 1, label: (tl || 0) + "/" + n, disabled: !n || drawing}, scene: {type: "select", id: "ai-library", value: lval, options: ldata, disabled: !(ldata && ldata.length)} }, (typeof status === "string" ? status : "") + (drawing ? " [drawing]" : "")); } """, Output("ai-deck-mirror", "data"), Input("ai-provider", "value"), Input("ai-model", "data"), Input("ai-model", "value"), Input("ai-effort", "data"), Input("ai-effort", "value"), Input("ai-effort", "disabled"), Input("ai-max-tokens", "value"), Input("ai-seed", "value"), Input("ai-timeline", "value"), Input("ai-history", "data"), Input("ai-library", "data"), Input("ai-library", "value"), Input("ai-stream-tick", "disabled"), Input("ai-status", "children"), State("ai-provider", "data"), prevent_initial_call=False, ) @callback( Output("ai-library", "data"), Input("ai-library-mount", "data"), prevent_initial_call=False, ) def _list_scenes(_mount): """Fill the library on first render — never on the public site, where the library does not exist (and must not be created).""" if not ANY_KEY: return [] try: return scene_library.options() except Exception: # noqa: BLE001 - a broken DB must not break the page traceback.print_exc() return [] @callback( Output("ai-library", "data", allow_duplicate=True), Output("ai-status", "children", allow_duplicate=True), Output("ai-status", "color", allow_duplicate=True), Input("ai-save-btn", "n_clicks"), State("ai-history", "data"), State("ai-prompt", "value"), State("ai-provider", "value"), State("ai-model", "value"), State("ai-effort", "value"), State("ai-max-tokens", "value"), State("ai-seed", "value"), prevent_initial_call=True, ) def _save_scene(n, hist, prompt, provider, model, effort, max_tokens, seed): """Save the generated scene, in draw order, with the settings that made it.""" if not n: return no_update, no_update, no_update if not ANY_KEY: return no_update, "The scene library is local-only.", "blue" elements = (hist or {}).get("elements") or [] try: sid = scene_library.save(elements, prompt=prompt or "", provider=provider, model=model, effort=effort, max_tokens=max_tokens, seed=seed) except ValueError as exc: return no_update, str(exc), "yellow" return (scene_library.options(), f"Saved scene #{sid} — {len(elements)} elements, in draw order, " f"to {scene_library.db_path().name}.", "green") @callback( Output("ai-canvas", "command", allow_duplicate=True), Output("ai-status", "children", allow_duplicate=True), Output("ai-status", "color", allow_duplicate=True), Output("ai-prompt", "value"), Input("ai-library", "value"), prevent_initial_call=True, ) def _load_scene(scene_id): """Put a saved scene back on the canvas (and its prompt back in the box, ready to iterate). The timeline picks it up like any other scene.""" if not scene_id or not ANY_KEY: return no_update, no_update, no_update, no_update row = scene_library.get(scene_id) if not row: return no_update, f"Scene #{scene_id} is not in the library.", "yellow", no_update cmd = { "id": f"lib-{scene_id}-{uuid.uuid4().hex[:8]}", "type": "updateScene", "payload": {"elements": row["elements"], "captureUpdate": "IMMEDIATELY"}, } status = (f"Loaded #{row['id']}: {row['title']} — {row['model'] or '?'} · " f"{row['n_elements']} elements. Scrub the timeline to replay it.") return cmd, status, "gray", row["prompt"] ``` :defaultExpanded: false :withExpandedButton: true --- *Source: /ai-agent* --- # API reference ## dash_excalidraw ### DashExcalidraw | prop | type | default | description | |---|---|---|---| | `id` | string | | Unique ID to identify this component in Dash callbacks. | | `UIOptions` | dict | | Subset of Excalidraw `UIOptions` that is JSON-serializable. Use this to toggle individual canvas actions, show/hide the welcome screen, etc. | | `appState` | objectOf | | Full serializable app state (view background, zoom, scroll, grid mode, zen mode, theme, active tool, …). Read-only from Python. | | `autoFocus` | bool | | Focus the canvas on mount. @,default,true | | `command` | dict | | Write to this prop from a Python callback to dispatch an imperative action into Excalidraw. Shape: ```python {"id": "unique-string", "type": "updateScene", "payload": {...}} ``` Supported `type` values: - `updateScene` / `resetScene` / `addFiles` - `scrollToContent` / `setActiveTool` / `setToast` / `toggleSidebar` - `updateLibrary` - `exportToSvg` / `exportToBlob` / `exportToCanvas` Each dispatch is de-duplicated by `id`, and the component clears the prop (sets it to `None`) once the action completes so React re-renders do not re-fire. | | `detectScroll` | bool | | Whether Excalidraw listens to wheel-scroll events on the canvas. @,default,true | | `docsLinkLabel` | string | | Visible label for the `docsLinkUrl` item. Re-point the URL and you should relabel: a menu entry that names one destination and opens another is the failure this pair exists to avoid. @,default,"dash-excalidraw docs" | | `docsLinkUrl` | string | | URL for the wrapper's own documentation item in the main menu. Rendered as its own group, independently of `hideExcalidrawLinks`. Set to `""` or `None` to render no item at all. @,default,"https://excalidraw.2plot.dev" | | `elements` | list of objectOf | | Current Excalidraw element array. Written via setProps on every scene change — read-only from Python callbacks. | | `externalizedSerializedData` | string | | Same envelope as `serializedData`, but every `files[*].dataURL` that still holds an inline `data:` URI is replaced with `null`. External URLs (those dispatched via the `replaceFiles` command) are retained as-is. Persist this variant to avoid paying the base64 cost; inline bytes can be rehydrated later via `dash_excalidraw.helpers.restore_inline_files`. | | `files` | objectOf | | Map of binary file entries (image id -> {dataURL, mimeType, ...}). Read-only from Python. | | `gridModeEnabled` | bool | | Snap to grid and draw the grid background. @,default,false | | `handleKeyboardGlobally` | bool | | When true, keyboard shortcuts work even when the canvas is not focused. Turn off if your Dash app has other inputs that might conflict. @,default,true | | `height` | string | | CSS height of the canvas container. Excalidraw fills its parent, so this is the number to change when the canvas looks too short. @,default,"600px" | | `hideExcalidrawLinks` | bool | | When `true` (default), the vendor's "Excalidraw links" group (GitHub / Follow us / Discord) is not rendered. Set `false` to show it. This is a render condition on THIS canvas's menu, so it works in both directions and each canvas on a page decides for itself. @,default,true | | `initialData` | dict | | Initial scene contents passed to Excalidraw on mount. Shape: `{elements, appState, files, libraryItems, scrollToContent}`. Updating this prop after mount has no effect — use `command` with `type="updateScene"` to change the scene imperatively. | | `interceptLinkOpens` | bool | | When `true`, the wrapper calls `event.preventDefault()` on every `lastLinkOpen` event so Python can handle the click itself (typically by opening a `dmc.Drawer`). Default `false` — links open in a new tab normally. | | `isCollaborating` | bool | | Renders the "currently-editing" collaborator UI. You'll also need to feed `appState.collaborators`; the wrapper does not bundle a transport layer. @,default,false | | `langCode` | string | | UI language code (e.g. `en`, `fr-FR`, `zh-CN`). @,default,"en" | | `lastExport` | objectOf | | Result of the most recent export command: `{timestamp, id, type, result, error?}`. Match `id` against the command you dispatched to correlate responses. | | `lastExternalDrop` | objectOf | | Fires when the wrapper's drop handler intercepts a drop that Excalidraw itself doesn't accept (non-image files, or any multi- file drop). Payload: { timestamp, files: [{name, mimeType, dataURL, size}, ...], dropPoint: {x, y}, # scene coords placeholderIds: [elemId, ...], # one id per non-image file, # pointing at the rectangle we # placed on the canvas so you # can update its `link` after # upload. } | | `lastFileAdded` | objectOf | | Fires when one or more new file ids appear in `files` with an inline `data:` dataURL. Payload: { timestamp, fileId, mimeType, dataURL, size, # first new file (back-compat) files: [ {fileId, mimeType, dataURL, size}, ... # every new file in this change ], } Single-file callbacks can keep reading `event['fileId']`; batch callbacks iterate `event['files']`. `size` is decoded byte count. | | `lastLibraryChange` | objectOf | | Snapshot of the last library change `{timestamp, items}`. | | `lastLinkOpen` | objectOf | | Snapshot of the last link-open event `{timestamp, elementId, url}` — fired when a user Cmd/Ctrl-clicks an element with a hyperlink. | | `lastPaste` | objectOf | | Snapshot of the last clipboard paste `{timestamp, data}`. The wrapper cannot cancel the paste from Python; if you need to intercept, clean up in a follow-up callback that modifies scene state afterward. | | `lastPointerDown` | objectOf | | Snapshot of the last pointer-down event: `{timestamp, activeTool, pointer: {x, y}}`. | | `lastPointerMove` | objectOf | | Throttled pointer-move snapshot `{timestamp, pointer, button, pointersMap}`. Throttled by `pointerMoveThrottleMs` (default 50 ms). | | `lastPointerUp` | objectOf | | Snapshot of the last pointer-up event: `{timestamp, activeTool, pointer: {x, y}}`. | | `lastScrollChange` | objectOf | | Throttled scroll/zoom snapshot `{timestamp, scrollX, scrollY}`. | | `libraryReturnUrl` | string | | Optional URL appended to the "Browse Library" button in the sidebar. When unset Excalidraw uses its own default. | | `name` | string | | Drawing name — appears in the top bar and in serialized export filenames. | | `pointerMoveThrottleMs` | number | | Debounce interval for `lastPointerMove` writes (milliseconds). @,default,50 | | `sceneVersion` | number | | Monotonic scene version, from the package's `getSceneVersion(elements)` export. Useful for change detection without diffing element arrays. It tracks ELEMENTS only. Registering a file, panning or zooming leaves it unchanged, so a callback that must see those should take `files` or `appState` as its Input rather than this. | | `scrollThrottleMs` | number | | Debounce interval for `lastScrollChange` writes (milliseconds). @,default,100 | | `serializedData` | string | | JSON string of the canonical Excalidraw serialized envelope `{type, version, source, elements, appState, files}`. Suitable to pass to `dash.dcc.Store` and later restore via `initialData`. | | `theme` | one of 'light', 'dark' | | Canvas color theme. @,default,"light" | | `validateEmbeddable` | bool \| list of string | | Controls which URLs may be embedded inside Excalidraw frames. Pass `true` to allow all, `false` to deny all, or a list of domain-glob strings (e.g. `["*.youtube.com", "excalidraw.com"]`) which the wrapper compiles to case-insensitive RegExps. | | `viewModeEnabled` | bool | | View-only mode: disables drawing tools; pan/zoom still available. @,default,false | | `welcomeScene` | objectOf | | A scene to open with when `initialData` is not given: `{elements, appState, files}`, the same shape `initialData` and `externalizedSerializedData` use, so a scene produced anywhere in this library can be pasted straight in. MOUNT-ONLY, like `initialData` — Excalidraw owns the scene afterwards. Dispatch `updateScene` to change it later. | | `welcomeScreen` | bool | | Show Excalidraw's welcome overlay on an empty canvas. REACTIVE, unlike `UIOptions.welcomeScreen`. The vendor reads that key once while the canvas is mounting, so a switch wired to it appears to do nothing — which is exactly how it read. This works by composing Excalidraw's `` as a CHILD, which React mounts and unmounts with the prop. MEASURED, because the obvious alternative looks right and is not: `appState.showWelcomeScreen` exists, but `updateScene({appState: {showWelcomeScreen: false}})` leaves it `true` — the vendor filters that key out of the merge, silently. Do not "fix" this back to an appState push. | | `welcomeScreenContent` | dict | | Words for the welcome overlay: `{title, subtitle}`. Either may be omitted. Supplying neither keeps Excalidraw's own wording. Only the TEXT is yours — the overlay's menu hints stay the vendor's, so they cannot drift out of step with the menu they describe. | | `width` | string | | CSS width of the canvas container. @,default,"100%" | | `zenModeEnabled` | bool | | Zen mode hides most of the chrome for a distraction-free canvas. @,default,false | --- # Basic usage > The minimum viable DashExcalidraw — one component, default props, a working canvas. --- ### Overview The smallest useful app is one component with default props. Draw on the canvas below — zoom, pan, undo, the shape tools, the library and the context menu all work with no configuration at all. That is the point of this page: **nothing on it is set up.** Everything you can do to the canvas is Excalidraw's own behaviour, reaching Dash unmodified. ### What you get for free Mounting `DashExcalidraw` with nothing but an `id` gives you the full editor: - **Every drawing tool** — rectangle, diamond, ellipse, arrow, line, freedraw, text, image, eraser and the frame tool, with keyboard shortcuts (`1`–`9`). - **The shape library**, including anything the user has saved locally. - **Undo and redo**, scoped to this canvas. - **Zoom and pan**, including scroll-to-zoom and space-drag. - **The context menu**, with copy/paste styles, grouping, layering and locking. - **Excalidraw 0.18's additions** — elbow arrows, flowchart shortcuts (`Cmd`/`Ctrl` + arrow key), scene search, image cropping, element linking and the command palette. None of that costs you a callback. ### The minimum app ```python from dash import Dash from dash_excalidraw import DashExcalidraw app = Dash(__name__) app.layout = DashExcalidraw(id="canvas", height="600px") if __name__ == "__main__": app.run(debug=True) ``` `height` is the prop you will actually change. Excalidraw fills its parent, so a canvas that looks too short is almost always a container-height problem rather than a component one. ### Live demo ### Reading what the user drew The component writes its state back through ordinary props, so a callback reads the canvas the same way it reads a dropdown: ```python from dash import Input, Output, callback @callback(Output("count", "children"), Input("canvas", "elements")) def show(elements): return f"{len(elements or [])} elements" ``` `elements` updates on every scene change. If you only need to know *that* something changed — not what — read `sceneVersion` instead; it is a single integer and far cheaper to compare than diffing the element array. ### Four switches you may need in a real app The defaults suit a canvas that owns its page. An app with other inputs, or a canvas embedded in a longer scrolling document, usually wants one or two of these changed. | Prop | Default | Turn it off when | |:-----|:--------|:-----------------| | `handleKeyboardGlobally` | `True` | Your page has other inputs. Shortcuts otherwise fire while the user types elsewhere. | | `autoFocus` | `True` | The canvas is below the fold, or another field should hold focus on load. | | `detectScroll` | `True` | The canvas sits inside a scrolling container and swallowing wheel events feels like a trap. | | `langCode` | `"en"` | You want another UI language — `"fr-FR"`, `"zh-CN"`, and so on. | ```python DashExcalidraw( id="canvas", handleKeyboardGlobally=False, # a form on the same page owns the keyboard autoFocus=False, detectScroll=False, # the page scrolls; the canvas should not eat it langCode="fr-FR", ) ``` `handleKeyboardGlobally` is the one worth thinking about first. It moves Excalidraw's key handling from the canvas to the document, which is what makes single-key shortcuts work without clicking the canvas — and also what puts it in the same room as every other keyboard consumer on your page. If you have your own shortcuts, a modal, or a form that shares the layout, turn it off and let the canvas take focus before it takes keys. ### Where to go next - [initialData](/initial-data) — seed the canvas at mount. - [Events](/events) — every Excalidraw callback, as a snapshot prop. - [Command dispatch](/commands) — drive the canvas from Python. - [Persistence](/persistence) — save a scene and restore it later. ### Source ```python # File: docs/basic-usage/basic.py """Basic usage: the minimum viable DashExcalidraw.""" import dash_mantine_components as dmc from dash_excalidraw import DashExcalidraw from docs._shared import canvas_frame, code_block, sync_canvas_theme sync_canvas_theme("basic-canvas") CODE = """ from dash import Dash from dash_excalidraw import DashExcalidraw app = Dash(__name__) app.layout = DashExcalidraw(id='canvas', height='600px') """ component = dmc.Stack( gap="md", children=[ code_block(CODE), canvas_frame(DashExcalidraw(id="basic-canvas", height="600px")), ], ) ``` :defaultExpanded: false :withExpandedButton: true ### Component reference Every prop on the component, generated from the TypeScript source. --- *Source: /basic* --- # Benchmark > Run one prompt across several efforts, token budgets or models — Claude against ChatGPT — and compare the drawings side by side. --- > **On this site these pages are documentation, not a hosted service.** > excalidraw.2plot.dev carries no provider keys, so generation is disabled > here and nothing below will spend anything. Everything on the page — > streaming onto the canvas, the cost estimate, the Stop button, the daily > spend ceiling — works when you run the repo locally with a `.env` holding a > provider key. This is deliberate and not a fault. ### Overview [AI agent](/ai-agent) answers *can it draw this?* This page answers the question you have immediately afterwards: **what do I give up by turning the knob down?** It sends one prompt to several settings at once and puts the drawings next to each other. Element counts and token totals rank the runs; looking at them tells you whether the extra tokens actually bought anything — which is not the same question, and is the reason every cell renders a real canvas rather than a row in a table. ### What the three axes mean **Effort** is thinking depth. On Claude Opus 5 it is largely a cost-and-latency control for this task: in a measured sweep, `high` cost 2.3× `low` and took 44% longer to produce one extra element, and `medium` produced *fewer* elements than `low`. Worth confirming on your own prompts — that is what the page is for. **Max tokens** is the lever that moves output. On Opus 5 it bounds thinking **and** response text together, so it is not a safety net but the main quality dial: tripling it took the same prompt from 24 elements to 31. **Model** is the third axis, and the only one that crosses providers: it puts a Claude cell and a ChatGPT cell in the same sweep, on the same prompt, at the same budget and the same effort. That last part is what makes it a comparison rather than two runs — matched settings, and a real price on each, where the published rates differ by up to 40× between the models offered here. Gemini is deliberately absent from this axis. It is called through a different signature with neither control and has no published price in this app, so a Gemini cell could show a drawing but never an honest cost or a matched setting. It remains available on [AI agent](/ai-agent). Every cell **streams**: the six drawings appear together, shape by shape, and each panel refits itself as its scene grows. A **Stop all** button is enabled for as long as a sweep is running — it closes every variant's connection to its provider, so generation stops and billing stops at the tokens already produced. What has been drawn stays on the canvases; a half-finished sweep is still a comparison, and usually the reason for stopping. Only one axis varies per run, and the page shows only the controls that axis reads — the others are hidden rather than left on screen looking live. Two moving variables make a comparison unreadable, and a full grid is a combinatorial bill. ### Live demo ### Reading the results Each panel shows the settings, the element count, wall time, token counts and an estimated cost. The status line reports total wall time alongside what the same run would have cost serially — the variants run **concurrently**, so a six-cell matrix takes roughly one generation's time rather than six. Three cautions before drawing conclusions: - **Element count is a crude proxy for quality.** A busier diagram is not a better one. The canvases are there to be looked at. - **These are single samples.** Model output varies run to run; repeat before trusting a small difference. - **Cost figures are local estimates**, not a bill — they ignore cache-write premiums and any discount. ### Source ```python # File: docs/benchmark/benchmark.py """Run one prompt across several settings at once and compare the results. The /ai-agent page answers "can it draw this?". This page answers the question you actually have afterwards: "what do I give up by turning this knob down?" — which needs the same prompt rendered several ways, side by side, with the cost of each. THREE THINGS THAT SHAPE THE DESIGN 1. Variants run CONCURRENTLY. They are network-bound, so a six-cell matrix costs roughly one generation's wall time instead of six. Run serially, a sweep takes long enough that nobody runs a second one. 2. The cost is shown BEFORE you press the button, not after. A six-cell Opus 5 matrix is real money, and an estimate that arrives with the results is an apology rather than a decision. 3. Every cell renders its own canvas in view mode. Element counts and token totals rank the runs; only looking at them tells you whether the extra tokens bought anything. """ from __future__ import annotations import dash_mantine_components as dmc from dash import ALL, Input, Output, State, callback, dcc, no_update from dash_excalidraw import DashExcalidraw from docs._shared import canvas_frame from lib import scene_stream, spend from lib.scene_ai import ( CLAUDE_EFFORT, CLAUDE_MAX_TOKENS, CLAUDE_MODELS, COMPARABLE_MODELS, EFFORT_CAPABLE, MODEL_LABEL, MODEL_PRICING, NO_KEYS_NOTICE, _spend_allowed, any_provider_configured, coerce_budget, estimate_cost, format_money, ) # Kept small on purpose. Every extra cell is another paid call, and the point # of the page is comparison, not exhaustiveness — beyond about six panels you # stop being able to see them at a glance, which is the whole feature. MAX_VARIANTS = 6 ANY_KEY = any_provider_configured() EFFORT_CHOICES = ["none", "low", "medium", "high", "xhigh", "max"] BUDGET_CHOICES = ["4000", "8000", "16000", "24000", "48000", "64000"] def _variants( model, axis, efforts, budgets, models, fixed_budget, fixed_effort ) -> list[tuple]: """The exact `(model, effort, budget)` list a run will execute. Shared by the estimate and the runner on purpose. The old estimate priced `n` variants at the LARGEST selected budget, which over-quoted every budget sweep — a 4K+8K+16K comparison was billed as three times 16K. It also ignored effort entirely, so the control the page exists to explore made no difference to the number above the button. Building the real list once fixes both, and means the quote cannot drift from the run. MODEL IS PER-VARIANT, not a single value alongside, because the third axis compares models across providers — a Claude cell and a ChatGPT cell in one sweep. The other two axes just repeat the one selected model. coerce_budget, not int(): `bm-fixed-budget` is a NumberInput and hands over whatever is in the box mid-edit ("64.000" crashed the estimate on /ai-agent). The chips are our own strings and always parse, but they go through the same door so there is one rule. """ if axis == "effort": budget = coerce_budget(fixed_budget, 24000) return [(model, e, budget) for e in (efforts or [])[:MAX_VARIANTS]] if axis == "model": budget = coerce_budget(fixed_budget, 24000) effort = fixed_effort or "low" return [(m, effort, budget) for m in (models or [])[:MAX_VARIANTS]] return [ (model, fixed_effort or "low", coerce_budget(b, 24000)) for b in (budgets or [])[:MAX_VARIANTS] ] def _variant_label(axis: str, model: str, effort: str, budget: int) -> str: """What a panel calls itself. On the model axis the model IS the finding, so it leads; elsewhere it is constant across cells and only clutters.""" if axis == "model": return f"{MODEL_LABEL.get(model, model)} · effort={effort}" return f"effort={effort} · {budget:,} tok" def _slot(index: int): """One cell's skeleton, built ONCE at import and then filled by callbacks. Panels used to be constructed from finished results, which is why the page could only show anything after every variant had returned. They are static now, with pattern-matching ids, so a callback can write into six canvases while the models are still drawing. Unused slots are hidden rather than absent — a component that does not exist cannot be an Output. """ return dmc.GridCol( id={"type": "bm-slot", "index": index}, style={"display": "none"}, span={"base": 12, "md": 6}, children=dmc.Paper( withBorder=True, p="sm", children=dmc.Stack( gap="xs", children=[ dmc.Box(id={"type": "bm-head", "index": index}), canvas_frame( DashExcalidraw( id={"type": "bm-canvas", "index": index}, height="340px", # View mode: these are specimens to compare, not # canvases to edit. It also stops a stray click in # one panel from changing what you are comparing. viewModeEnabled=True, ), min_height=340, ), ], ), ), ) def _cell_cost(model: str, meta: dict | None) -> float: if not meta: return 0.0 price = MODEL_PRICING.get(model, (0, 0)) return ( meta["input_tokens"] * price[0] + meta["output_tokens"] * price[1] ) / 1_000_000 def _head(cell: dict, state: dict): """The badges above one cell's canvas, from whatever is known so far.""" if state.get("error"): return dmc.Stack( gap=4, children=[ dmc.Badge(cell["label"], color="red", variant="light"), dmc.Text(state["error"], size="xs", c="red"), ], ) drawn = len(state.get("all", [])) badges = [dmc.Badge(cell["label"], variant="light")] badges.append( dmc.Badge( f"{drawn} element{'s' if drawn != 1 else ''}", color="violet", variant="light", ) ) badges.append( dmc.Badge(f"{state.get('elapsed', 0.0):.0f}s", color="gray", variant="light") ) meta = state.get("meta") if state.get("cancelled"): badges.append(dmc.Badge("stopped", color="orange", variant="filled")) elif not state.get("done"): badges.append(dmc.Badge("drawing…", color="blue", variant="dot")) if meta: badges.append( dmc.Badge( f"~${_cell_cost(cell['model'], meta):.3f}", color="teal", variant="light", ) ) detail = "" if meta: detail = f"{meta['output_tokens']:,} out / {meta['input_tokens']:,} in" stop = meta.get("stop_reason") if stop in ("max_tokens", "incomplete"): detail += f" · TRUNCATED at {meta['max_tokens']:,} tokens" elif stop and stop not in ("end_turn", "completed"): detail += f" · stop={stop}" if state.get("lost"): detail += f" · {state['lost']} lost from the buffer" return dmc.Stack( gap=4, children=[ dmc.Group(gap="xs", children=badges), dmc.Text(detail, size="xs", c="dimmed"), ], ) component = dmc.Stack( gap="md", children=[ dmc.Alert( NO_KEYS_NOTICE, title="AI generation is disabled on this site", color="blue", variant="light", style={} if not ANY_KEY else {"display": "none"}, ), dmc.Alert( title="This page spends real API credits", color="yellow", style={"display": "none"} if not ANY_KEY else {}, children=( "Each variant is a separate paid model call. The estimate below " "updates as you change the matrix — check it before running." ), ), dmc.Paper( withBorder=True, p="md", children=dmc.Stack( gap="sm", children=[ dmc.Grid( gutter="md", children=[ dmc.GridCol( dmc.Select( id="bm-model", label="Model", data=COMPARABLE_MODELS, value=COMPARABLE_MODELS[0]["value"], ), id="bm-model-col", span={"base": 12, "sm": 4}, ), dmc.GridCol( dmc.SegmentedControl( id="bm-axis", data=[ {"value": "effort", "label": "Vary effort"}, {"value": "budget", "label": "Vary max tokens"}, {"value": "model", "label": "Compare models"}, ], value="effort", fullWidth=True, ), span={"base": 12, "sm": 8}, ), ], ), # Only one axis varies at a time. A grid over both is a # combinatorial bill, and two variables moving at once is # exactly what makes a comparison unreadable. # # ONLY THE ACTIVE AXIS IS SHOWN. Both lists used to render # together, always enabled, while the segmented control # above decided which one the run actually read — so # ticking "Max-token budgets to compare" while the axis sat # on its "Vary effort" default changed nothing, including # the price. The estimate was right and the page was # lying: it offered an input it then ignored. Hiding the # inactive pair is the fix, not making the price react to # a control the run does not read. dmc.CheckboxGroup( id="bm-efforts", label="Effort levels to compare", value=["low", "high"], children=dmc.Group( [dmc.Checkbox(label=e, value=e) for e in EFFORT_CHOICES], gap="md", ), ), dmc.CheckboxGroup( id="bm-budgets", label="Max-token budgets to compare", value=["8000", "24000"], style={"display": "none"}, # axis defaults to "effort" children=dmc.Group( [ dmc.Checkbox(label=f"{int(b):,}", value=b) for b in BUDGET_CHOICES ], gap="md", ), ), # The cross-provider axis. Every entry here accepts a # budget and an effort and has a published price, so a # Claude cell and a ChatGPT cell are genuinely comparable: # same prompt, same budget, same effort, and a cost on # each. Gemini is deliberately absent — see # COMPARABLE_MODELS in lib/scene_ai.py. dmc.MultiSelect( id="bm-models", label="Models to compare", description=( "Mix providers freely — the same prompt, budget and " "effort go to each" ), data=COMPARABLE_MODELS, value=["claude-opus-5", "gpt-6-astra"], maxValues=MAX_VARIANTS, clearable=True, style={"display": "none"}, # axis defaults to "effort" ), dmc.Grid( gutter="md", children=[ dmc.GridCol( dmc.NumberInput( id="bm-fixed-budget", label="Max tokens (held constant)", description="Every effort variant runs at this budget", value=24000, min=1000, max=128000, step=4000, ), id="bm-fixed-budget-col", span={"base": 12, "sm": 6}, ), dmc.GridCol( dmc.Select( id="bm-fixed-effort", label="Effort (held constant)", description="Every budget variant runs at this effort", data=[ {"value": e, "label": e} for e in EFFORT_CHOICES ], value="low", ), id="bm-fixed-effort-col", span={"base": 12, "sm": 6}, style={"display": "none"}, # axis defaults to "effort" ), ], ), dmc.Textarea( id="bm-prompt", label="Prompt", description="The same prompt is sent to every variant — that is what makes them comparable", placeholder="E.g. 'an architecture diagram of a payments service: api, ledger, queue, two databases, with retry paths'", autosize=True, minRows=3, ), dmc.Group( [ dmc.Button( "Run benchmark", id="bm-run", disabled=not ANY_KEY, ), # THE BRAKES. This page is the reason they matter # most: one click is up to six paid calls running # at once, so a stop here is worth six times what # it is worth on /ai-agent. dmc.Button( "Stop all", id="bm-stop", leftSection="■", color="red", disabled=True, ), dmc.Text(id="bm-estimate", size="sm", c="dimmed"), ], justify="space-between", ), ], ), ), dmc.Alert( id="bm-status", title="Status", color="gray", children="Ready.", ), # Six fixed slots, hidden until used. Previously this was an empty # Div filled with finished panels, which is why nothing could appear # until everything had. dmc.Grid(gutter="md", children=[_slot(i) for i in range(MAX_VARIANTS)]), # One ticker for the whole sweep, not one per cell: six Intervals # would mean six callbacks a second arguing over the same Store. dcc.Store(id="bm-runs", data=None), dcc.Interval(id="bm-tick", interval=500, disabled=True), ], ) @callback( Output("bm-efforts", "style"), Output("bm-budgets", "style"), Output("bm-models", "style"), Output("bm-model-col", "style"), Output("bm-fixed-budget-col", "style"), Output("bm-fixed-effort-col", "style"), Input("bm-axis", "value"), ) def _show_active_axis(axis): """Show only the controls the run will actually read. The segmented control decides which list becomes the variants and which values are held constant; everything else is inert. Leaving it all on screen made the inert controls look live — tick three budgets while the axis says "Vary effort" and nothing happens, price included. Note the single Model select disappears on the model axis: there, the model is the thing being varied, so one fixed model would be a control that contradicts the axis. """ shown: dict = {} hidden = {"display": "none"} def vis(active: bool): return shown if active else hidden return ( vis(axis == "effort"), # effort levels to compare vis(axis == "budget"), # max-token budgets to compare vis(axis == "model"), # models to compare (cross-provider) vis(axis != "model"), # the single model select vis(axis != "budget"), # the budget held constant vis(axis != "effort"), # the effort held constant ) @callback( Output("bm-estimate", "children"), Input("bm-model", "value"), Input("bm-axis", "value"), Input("bm-efforts", "value"), Input("bm-budgets", "value"), Input("bm-models", "value"), Input("bm-fixed-budget", "value"), Input("bm-fixed-effort", "value"), ) def _estimate_cost(model, axis, efforts, budgets, models, fixed_budget, fixed_effort): """Price the matrix BEFORE it runs, per variant. See the module docstring. One click here is up to six paid calls, so this number is the last thing between a curious click and a real bill. It prices each variant at its own effort and its own budget — the two things the page lets you vary — and shows the ceiling beside the typical figure, because `max_tokens` bounds the spend but does not determine it. """ if not ANY_KEY: return "No provider keys on this site — nothing is spent here." variants = _variants( model, axis, efforts, budgets, models, fixed_budget, fixed_effort ) if not variants: return "Select at least one variant." ests = [(m, estimate_cost(m, e, b)) for m, e, b in variants] unpriced = sorted({m for m, x in ests if not x["priced"]}) if unpriced: return f"{len(variants)} variants · no price on file for {', '.join(unpriced)}." typical = sum(x["typical"] for _, x in ests) ceiling = sum(x["ceiling"] for _, x in ests) n = len(variants) # Name the axis in the number. Three controls can each produce "3 # variants", and when the price surprises someone the first useful fact is # which of them the run is actually reading. sweeping = {"effort": "effort", "budget": "max tokens", "model": "models"}[axis] head = ( f"{n} variant{'s' if n != 1 else ''} varying {sweeping} · about " f"{format_money(typical)} for the sweep, at most " f"{format_money(ceiling)} if every one runs its budget out." ) # Where the cells differ in price, the spread is the interesting part: a # single total hides which one is doing the spending. That is most acute # on the model axis, where rates differ by up to 40x between providers. if n > 1 and axis in ("budget", "model"): lo = min(ests, key=lambda pair: pair[1]["typical"]) hi = max(ests, key=lambda pair: pair[1]["typical"]) if axis == "model": head += ( f" Cheapest {MODEL_LABEL.get(lo[0], lo[0])} " f"~{format_money(lo[1]['typical'])}, dearest " f"{MODEL_LABEL.get(hi[0], hi[0])} " f"~{format_money(hi[1]['typical'])}." ) else: head += ( f" Cheapest cell ~{format_money(lo[1]['typical'])}, " f"dearest ~{format_money(hi[1]['typical'])}." ) # Only meaningful when one model spans the sweep; on the model axis the # per-model note would be ambiguous, and the estimate already prices each # cell correctly either way. if axis != "model" and model not in EFFORT_CAPABLE: head += " (This model ignores effort, so every cell costs the same.)" return head BLANK = {"display": "none"} SHOWN: dict = {} @callback( Output("bm-runs", "data"), Output("bm-tick", "disabled"), Output("bm-status", "children"), Output("bm-status", "color"), Output({"type": "bm-slot", "index": ALL}, "style"), Output({"type": "bm-head", "index": ALL}, "children"), Output({"type": "bm-canvas", "index": ALL}, "command"), Input("bm-run", "n_clicks"), State("bm-model", "value"), State("bm-axis", "value"), State("bm-efforts", "value"), State("bm-budgets", "value"), State("bm-models", "value"), State("bm-fixed-budget", "value"), State("bm-fixed-effort", "value"), State("bm-prompt", "value"), prevent_initial_call=True, ) def _run( _clicks, model, axis, efforts, budgets, models, fixed_budget, fixed_effort, prompt ): """START every variant, then return. The cells fill in as they draw. This used to block until all six calls had finished and then build the panels from their results, which meant a minute or more of spinner and — more to the point — no way to stop once the money was committed. Each variant is now a streamed run in the shared buffer, so the page can show six drawings appearing at once AND cancel them. """ blank = [BLANK] * MAX_VARIANTS nothing = [no_update] * MAX_VARIANTS def refuse(message, color="yellow"): return None, True, message, color, blank, nothing, nothing # THIS PAGE HAD NO KEY CHECK AT ALL — measured 2026-09-12 against a # keyless process: it started every variant, enabled the ticker, and each # cell failed separately from its worker thread. A spinner followed by six # red panels, for a site that is never going to have keys. Refused here # instead, in the same words and colour as the notice on the page. if not ANY_KEY: return refuse(NO_KEYS_NOTICE, "blue") if not prompt or not prompt.strip(): return refuse("Write a prompt first.") # Same gate as /ai-agent, and it matters more here: one click is up to six # paid calls. See lib/scene_ai._spend_allowed. if not _spend_allowed(): return refuse( "Sign in to run a benchmark — this page spends real API credits." ) # Same builder the estimate uses, so the run cannot execute a different # matrix from the one that was priced above the button. variants = _variants( model, axis, efforts, budgets, models, fixed_budget, fixed_effort ) if not variants: return refuse("Select at least one variant to compare.") if axis == "effort" and model not in EFFORT_CAPABLE: # Varying effort on a model that rejects the parameter would run N # identical calls and present them as a comparison — worse than an # error, because the output looks like a result. if len({e for _, e, _ in variants}) > 1: return refuse( f"{model} does not accept the effort parameter, so every variant " "would be identical. Switch to varying max tokens, or pick " "another model.", "red", ) # The model axis has its own version of the same trap: one model selected # is not a comparison, it is a single call wearing a comparison's UI. if axis == "model" and len(variants) < 2: return refuse("Pick at least two models to compare — one is just a single run.") # Priced as a SWEEP, not per cell: six calls admitted one at a time would # each pass a check the six together fail, which is precisely the runaway # this page is most able to cause. try: spend.check( sum( estimate_cost(m, e, b)["typical"] for m, e, b in variants ) ) except spend.CeilingReached as exc: return refuse(str(exc)) cells = [] styles = list(blank) heads = list(nothing) commands = list(nothing) failed = [] for index, (variant_model, effort, budget) in enumerate(variants): label = _variant_label(axis, variant_model, effort, budget) try: run_id = scene_stream.start( model=variant_model, user_prompt=prompt.strip(), max_tokens=budget, effort=effort, ) except Exception as exc: # noqa: BLE001 - one bad variant, not the sweep # A cell that cannot start must not take the others down with it; # that is the whole reason the sweep is worth running. failed.append(f"{label}: {type(exc).__name__}: {exc}") continue cell = { "id": run_id, "label": label, "model": variant_model, "cursor": 0, "done": False, } cells.append(cell) styles[index] = SHOWN heads[index] = _head(cell, {"all": [], "elapsed": 0.0, "done": False}) # Blank the cell so the drawing starts from nothing rather than # appearing over the previous sweep's scene. commands[index] = { "id": f"bm-reset-{run_id[:8]}", "type": "resetScene", "payload": {}, } if not cells: return refuse("No variant could be started. " + " · ".join(failed), "red") status = f"Running {len(cells)} variant{'s' if len(cells) != 1 else ''}…" if failed: status += f" ({len(failed)} could not start: {'; '.join(failed)})" return cells, False, status, "gray", styles, heads, commands @callback( Output("bm-status", "children", allow_duplicate=True), Output("bm-status", "color", allow_duplicate=True), Output("bm-runs", "data", allow_duplicate=True), Output("bm-tick", "disabled", allow_duplicate=True), Output({"type": "bm-head", "index": ALL}, "children", allow_duplicate=True), Output({"type": "bm-canvas", "index": ALL}, "command", allow_duplicate=True), Input("bm-tick", "n_intervals"), State("bm-runs", "data"), prevent_initial_call=True, ) def _tick(_n, cells): """Collect every cell's new elements in ONE poll. One ticker for the whole sweep rather than one per cell: six Intervals would be six callbacks a second contending for the same Store, and Dash gives no ordering guarantee between them. """ nothing = [no_update] * MAX_VARIANTS if not cells: return no_update, no_update, no_update, True, nothing, nothing heads = list(nothing) commands = list(nothing) next_cells = [] finished = 0 total_cost = 0.0 total_elements = 0 slowest = 0.0 for index, cell in enumerate(cells): state = scene_stream.take(cell["id"], cell.get("cursor", 0)) if not state["found"]: # Expired, forgotten, or an instance restart took the store. Treat # it as finished rather than polling forever. next_cells.append({**cell, "done": True}) finished += 1 continue heads[index] = _head(cell, state) if state["elements"]: commands[index] = { "id": f"bm-{cell['id'][:8]}-{state['cursor']}", "type": "updateScene", "payload": { "elements": state["all"], # NEVER while drawing, or each poll is its own undo step. "captureUpdate": "NEVER", # These cells are 340px showing scenes laid out for # 1200x800. Without refitting you watch a zoomed-in corner # of a drawing rather than the drawing. "scrollToContent": True, }, } total_elements += len(state["all"]) slowest = max(slowest, state["elapsed"]) if state["done"]: finished += 1 total_cost += _cell_cost(cell["model"], state.get("meta")) if not cell.get("done"): # Last poll for this cell: commit it as one undo step, then # drop it from the buffer. commands[index] = { "id": f"bm-final-{cell['id'][:8]}", "type": "updateScene", "payload": { "elements": state["all"], "captureUpdate": "IMMEDIATELY", "scrollToContent": True, }, } scene_stream.forget(cell["id"]) next_cells.append({**cell, "cursor": state["cursor"], "done": True}) else: next_cells.append({**cell, "cursor": state["cursor"]}) all_done = finished == len(cells) if not all_done: status = ( f"Drawing… {finished}/{len(cells)} variants finished · " f"{total_elements} elements so far ({slowest:.0f}s)" ) return status, "gray", next_cells, False, heads, commands cancelled = sum(1 for c in cells if c.get("cancelled")) status = ( f"{len(cells)} variant{'s' if len(cells) != 1 else ''} in {slowest:.0f}s " f"(wall clock — they ran together) · {total_elements} elements · " f"~${total_cost:.3f} total" ) return status, "yellow" if cancelled else "green", next_cells, True, heads, commands @callback( Output("bm-status", "children", allow_duplicate=True), Output("bm-status", "color", allow_duplicate=True), Output("bm-runs", "data", allow_duplicate=True), Output("bm-tick", "disabled", allow_duplicate=True), Input("bm-stop", "n_clicks"), State("bm-runs", "data"), prevent_initial_call=True, ) def _stop(_clicks, cells): """Press the brakes on every variant at once. Six calls are six bills, so this cancels them all rather than asking which one. Each `cancel` closes that run's provider stream, so generation stops and billing stops at the tokens already produced — ending the poll alone would leave six models running to their full budgets unobserved. What is drawn stays drawn: a half-finished sweep is still a comparison, and it is usually the reason for stopping. """ if not cells: return no_update, no_update, no_update, True stopped = sum(1 for cell in cells if scene_stream.cancel(cell["id"])) return ( f"Stopped {stopped} variant{'s' if stopped != 1 else ''}. What was drawn " f"is kept; no further tokens are being generated.", "yellow", [{**cell, "cancelled": True} for cell in cells], True, ) @callback( Output("bm-run", "loading"), Output("bm-run", "disabled"), Output("bm-stop", "disabled"), Output("bm-prompt", "disabled"), Output("bm-axis", "disabled"), Input("bm-tick", "disabled"), ) def _lock_controls(tick_disabled): """Keyed on the ticker, not on `_run`'s lifetime — that now returns in milliseconds, so a `running=` lock would release while six models were still drawing.""" sweeping = not tick_disabled # `or not ANY_KEY` keeps Run off for good on a keyless deployment; without # it this callback re-enables it on first render. off = sweeping or not ANY_KEY # Stop is enabled precisely when a sweep is running. return sweeping, off, not sweeping, off, off ``` :defaultExpanded: false :withExpandedButton: true --- *Source: /benchmark* --- # Changelog > Version history of dash-excalidraw. The timeline on this page is rendered from `CHANGELOG.md`, reproduced below. --- All notable changes to `dash-excalidraw` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] #### Added - **`welcomeScreen`, `welcomeScreenContent` and `welcomeScene` props.** `UIOptions.welcomeScreen` is read once while the canvas mounts, so a control bound to it does nothing after the first paint. The overlay's real state is `appState.showWelcomeScreen`, so `welcomeScreen` drives that instead and toggles live. `welcomeScreenContent={"title": …, "subtitle": …}` puts your own words on it. `welcomeScene` sets the scene the canvas opens with when `initialData` is absent — the same `{elements, appState, files}` shape, so a scene from anywhere in this library can be pasted in. - **`/trace-image` hands the trace back as copyable scene JSON**, taken from `externalizedSerializedData` so the inline reference image is stripped out. Draw or trace a scene, copy it, paste it into `welcomeScene` or `initialData`. - **`/scene-viewer`**: paste or upload raw scene JSON and render it on a live canvas. It is the other half of `/trace-image`. It accepts a full `.excalidraw` envelope, anything shaped like `initialData`, a bare element array, a model's fenced reply, and `serializedData` quoted once too often. Before rendering, it reports what Excalidraw's loader would otherwise drop without a word: unknown types, invisibly small elements, duplicate ids, and images whose bytes were externalized to `null`. No model is called, so it works on this site. It also documents a reusable pattern: a render is four commands fed one at a time through a `dcc.Store` queue, advanced each time the canvas clears `command`. - **Claude Opus 5.5 on `/ai-agent`, `/benchmark` and `/trace-image`** (`claude-opus-5-5`, $4 / $20 per 1M tokens). Its image input, all five effort levels and its 1M / 128K limits were read from `GET /v1/models` on 2026-09-22. Its API default effort is `medium`, not `high`, so the selector starts at an explicit `low` and the "none" estimate is priced as medium. Claude Opus 5 stays the default model. #### Changed - **The sidebar reads Getting started → Appearance → Data flow → Advanced.** Appearance moved ahead of Data flow. Inside Advanced, Coverage moved to the end: it shared `order: 6` with Trace an image and sorted between Benchmark and Trace by name alone. #### Fixed - **The mobile drawer closes when you pick a page.** Drawer links route client-side, so the drawer stayed open with its overlay over the page you had just chosen until a second tap on the hamburger. Recorded as DIVERGENCES.md 18. It is template-class and should be filed upward. - **Documented: an embed always draws above every ordinary element**, whatever the scene z-order says, so "bring to front" on a shape does nothing against a GIF. Measured in the DOM — the static canvas holding every shape, image and text is one bitmap at z-index 1, and the iframe container is a DOM layer at z-index 2. It is upstream Excalidraw behaviour, identical for a YouTube embed on excalidraw.com, and there is no setting that fixes it. - **The toolbar's "insert image" now takes GIFs down the same path as a drop.** Dropping worked and picking did not, which was not a second bug but a second door: Excalidraw opens its picker with `browser-fs-access`, which uses `window.showOpenFilePicker` where it exists (Chrome) and a hidden `` otherwise — neither reaches the drop handler. Both are intercepted, and a picked GIF is re-dispatched as a synthetic drop so it reuses the proven path rather than a second copy of it. Non-GIF picks pass through untouched. - **The upload activity table scrolls sideways** instead of running past its card and clipping the status column — the one that says whether the upload worked. - **A GIF is identified by its bytes, not by the drag's MIME type.** A drag can arrive with `type` empty — measured, such a GIF was stored as `.bin` with mime `application/octet-stream`, so the page could not tell it was a GIF and never built the embed. The component sniffs the GIF magic, rewrites the dataURL prefix, and reads the size from the 10-byte header instead of decoding the file (which was reintroducing the very main-thread stall the interception exists to avoid). - **An upload over the per-file cap is answered, not crashed.** `FileTooLarge` used to leave the callback: HTTP 500, a placeholder on the canvas that never resolved, and nothing saying why. The upload table now shows `too large` in red with the limit and the env var that raises it. - **Animated GIFs survive the drop, and no longer freeze the tab.** Excalidraw rasterises a dropped GIF to a single still frame before anything downstream sees it — measured, a 123,069-byte 12-frame GIF89a arrived as a 2,820-byte PNG with none. The component now intercepts GIF drops and sends the original bytes down the `lastExternalDrop` path, exactly like a `.pdf`; Excalidraw never decodes them. `/file-uploads` stores those bytes and puts an `embeddable` where the placeholder was, so the browser animates the real file. Verified end to end: 123,069 bytes stored, `GIF89a`, 12 frames, iframe live on the canvas. The rasterisation was also what froze the tab on a large GIF — a 5.17 MB one left the renderer unable to answer a debugger evaluation at all — so not decoding it fixes both symptoms. The trade: a GIF is an embed rather than an image element, so it is not croppable or styleable on the canvas. - **The storage backend is a seam** (`lib/file_backends.py`): `put`, `get`, `url_for`. `EXCALIDRAW_FILE_BACKEND` selects `memory` (default) or `disk` (`EXCALIDRAW_FILE_DIR`), and an unknown name raises at boot rather than falling back — a store that is silently not the one you configured is worse than a failure to start. Implement those three methods and `register_backend` to point uploads at Cloudflare R2, S3 or Postgres; nothing above storage changes, because the canvas only ever needed a URL back. `/file-uploads` explains the whole path and shows which backend is live, and `scripts/stress_file_uploads.py` re-measures the caps, eviction and TTL. - **`replaceFiles` never replaced anything.** It was built on `api.addFiles` overwriting an entry whose id already exists — measured in a browser, that is a silent no-op, and there is no `removeFiles` and no `updateScene({files})` either. So every `/file-uploads` drop uploaded correctly and the canvas kept its base64, which is why the GIF auto-embed never produced an iframe: that page waits for a file whose `dataURL` has become a URL and there never was one. The command now stores the new bytes under a fresh id and repoints the elements that referenced the old one, and reports the file store so callbacks watching `files` actually fire. - **`resetScene` silently discarded every mode the props had asked for.** It restores Excalidraw's default appState, so a canvas mounted with `viewModeEnabled` (or zen/grid mode, a `name`, a `theme`) quietly came back editable — measured as 1 toolbar button before the reset and 17 after — and then snapped back on the next React re-render, stranding anything drawn in between. `/trace-image` resets the scene at the start of every trace, so this was the ordinary path. The command now re-asserts what the props say. - **`/trace-image`'s canvas is editable.** It was view-only, on the theory that a specimen being compared should not change under a stray click. Now that the scene JSON below it is copyable, tidying the trace before taking it away is the point. - **`sceneVersion` was never computed.** `getSceneVersion` is a standalone export of `@excalidraw/excalidraw`, not a method on the imperative API; the component called it as a method behind a `typeof === "function"` guard, so it was always `undefined` and the guard made that silent. The prop never reached Python and any callback holding it as an Input never fired — which is why `/coverage`'s read-only panel sat at null however much you drew. - **`addFiles` registered files nothing could observe.** It touches no element, so Excalidraw fires no change event and the `files` prop never mentioned the file just added. The command now reports the file store itself. - **`toggleSidebar` was being given a tab name as a sidebar name.** Excalidraw's built-in sidebar is `"default"`; `"library"` and `"search"` are tabs within it, so `{name: "library"}` addressed nothing and returned false. `/library`'s and `/commands`' buttons now pass `{name: "default", tab: "library"}`, and the component warns when a `toggleSidebar` finds no such sidebar rather than letting the command evaporate. - **`/ui-options`' two link-state canvases were side by side** in a column too narrow for the hamburger menu they exist to demonstrate, so the menu covered its own canvas. Stacked. #### Note for readers of the deployed site **The AI pages on are documentation, not a hosted service.** That deployment carries no provider keys, so `/ai-agent`, `/benchmark` and `/trace-image` show a notice and their run controls are disabled. Nothing there spends anything, and nothing is broken — the owner declined to spend tokens on demos for anonymous visitors, which is a deliberate decision and not a misconfiguration. Everything described below works when you run the repo locally with a `.env` holding a provider key: streaming onto the canvas, the cost estimate, the Stop button and the daily spend ceiling included. #### Added - **ChatGPT joins Claude and Gemini on `/ai-agent`, and `/benchmark` can now compare the two head to head.** GPT-6 Astra, GPT-5.6 Sol, Terra and Luna, called through the Responses API — `instructions`, `input`, `max_output_tokens` and `reasoning.effort` map onto the page's existing three controls with no translation. `/benchmark` gains a third axis, "Compare models", which puts a Claude cell and a ChatGPT cell in one sweep at the same prompt, budget and effort; matched settings and a real price on each are what make it a comparison rather than two runs. Set `CHATGPT_API_KEY` (`OPENAI_API_KEY` is accepted as a fallback). Gemini is deliberately excluded from the compare axis: it takes neither control and has no published price in this app, so a cell for it could show a drawing but never an honest cost. It stays available on `/ai-agent`. - **`/ai-agent` draws the scene as it arrives instead of showing a loading overlay.** Claude and ChatGPT runs stream: elements are parsed out of the token stream as each one's braces close and dispatched to the canvas by a 400ms poll, so the first shape lands in a few seconds rather than after the whole generation. The status line counts elements and elapsed seconds while it draws. Intermediate updates use `captureUpdate: NEVER` and the final one `IMMEDIATELY`, so the whole drawing is a single undo step rather than one per poll. Gemini keeps the one-shot path — its SDK has no streaming call. - **A daily spend ceiling across every AI page and provider.** The sign-in gate stops anonymous spending; it does nothing about a signed-in visitor running `/benchmark` thirty times, or a model deciding a prompt deserves its whole 128K budget. `lib/spend.py` holds one constant — `DAILY_CEILING_USD`, the site owner's only dial — and refuses a call that would take the day past it, with a message that says what the limit is, what has gone, and that it resets at midnight UTC. `/ai-agent`'s cost label shows what is left. Admission uses the typical cost estimate and settlement records the actual one, so the day can overshoot by at most one run's difference between the two — bounded, not zero, and stated that way in the module rather than implied to be a hard cap. The ledger is diskcache-backed for the same reason the scene buffer is: a counter in a module global would give each of the two gunicorn workers its own budget, making the real ceiling a function of `WEB_CONCURRENCY`. The ledger lives under the system temp directory, which on Render is inside the container — shared by both workers, as the ceiling requires, and reset on every deploy, so a redeploy starts the day over. Point `AI_SPEND_DIR` at a persistent disk if a day should survive deploys. - **`/trace-image`** — upload a reference image and have the model redraw it with Excalidraw's own primitives, streaming onto the canvas beside the original. Same controls as `/ai-agent` (model, effort, max tokens) with the cost estimate accounting for the image's input tokens, which a prompt-only page does not have to. The system prompt is spliced from the shared one, so the JSON contract and the parser are identical and only the task changes; it tells the model to match layout, structure, text and colour in that order, and explicitly NOT to chase photographic detail with hundreds of freedraw strokes, which exhausts the budget before the layout is down. Models are refused an image unless they are in `VISION_MODELS` — a model that silently ignores one would trace from the prompt alone and return a confident drawing of nothing in particular. - **`/benchmark` streams every cell, and has a Stop all button.** The six drawings now appear together as they are made, each panel refitting itself as its scene grows, instead of a spinner followed by six finished panels. The button stops every variant at once — one click here is up to six paid calls, so it is worth six times what it is worth on `/ai-agent`. - **A Stop button on `/ai-agent` and `/trace-image`.** Presses the brakes on a generation in flight: it closes the provider stream, so the model stops generating and billing stops at the tokens already produced. Ending the poll alone would have left the run going to its full budget with nobody reading it. The cancel flag lives in the shared store, so it works when the click is handled by a different worker from the one running the generation. What is already drawn stays on the canvas — a stop is not an undo. #### Changed - **The AI provider SDKs are now installed on deployed commits, which makes `/ai-agent` and `/benchmark` able to call anything there for the first time.** `anthropic`, `openai` and `google-genai` were an optional `pyproject` extra that the Dockerfile never installs, so on every deploy to date the pages rendered and every click died on an `ImportError`. They are now pinned in `requirements.txt`. **This is a behaviour change to the deployed site, not a dependency bump** — those pages can spend real API credits from the moment a key is present in the environment. Both remain behind `tier: auth` and the signed-in spend gate. Pinned with `==` rather than a floor, to the versions this app's calls have actually gone through (`anthropic==0.96.0`, `openai==3.11.0`, `google-genai==1.73.1`). `anthropic` 1.4.0 and `google-genai` 2.22.0 both exist and are each a major version ahead; the commit that first makes the lane live is the wrong place to discover what changed in them. #### Fixed - **A generation lasting longer than five minutes ate its own beginning.** In-flight elements were stored with the same 300-second expiry used to retire an idle run, so on a long generation the earliest elements expired while the model was still drawing: the canvas lost roughly one shape for every shape it gained and the count plateaued. Measured on a real 358-second run that finished with 145 elements. Elements now carry an expiry that outlives the longest possible run, and `take()` COUNTS elements it cannot read back instead of quietly returning a shorter list — the silence is what made this look like a model that had stopped drawing. - **Streamed elements were not normalised, so long scenes stopped growing.** Observed on `/ai-agent` with `gpt-6-astra`: past roughly 150 elements the canvas appeared to delete one shape for every new one. `updateScene` reconciles by element id, so an element carrying an id the scene already holds REPLACES it — a model that repeats ids therefore caps the scene at the number of distinct ids it emits, with no error anywhere. Streamed elements now go through the same `_coerce_types` normalisation the blocking path always used (which also fills in `version`, `versionNonce`, `seed` and `isDeleted`), and a repeated id is renamed rather than allowed to overwrite. - **`/ai-agent`'s status line priced every run from the Claude table**, so a ChatGPT run reported no cost at all — which reads as "this was free". - **A budget-truncated scene said `stop=max_tokens` and nothing else.** It now says it was truncated and names the budget, since hitting it is the most common reason a drawing comes out shorter than asked for. A truncated ChatGPT stream is also no longer raised as an error: the elements that arrived are real shapes already on the canvas, and presenting a partial success as a failure is wrong. - **In-flight generations are stored in a shared cache rather than a per-process dict.** The production image runs `gunicorn --workers 2`, so a poll balanced to the worker that is not running the generation would have found no such run and reported that it vanished — roughly half of them, at random, with nothing in any log. Impossible to reproduce locally, where `python run.py` is a single process. The buffer is now backed by diskcache (already a dependency), and a test spawns a second interpreter to prove a separate process can read a run. - `_call_claude` carried two consecutive docstrings, so `help()` showed only the first and the streaming rationale was invisible. Merged. Pre-existing; harmless at runtime, invisible to flake8 and pytest. ## [1.0.0] — unreleased Ground-up TypeScript rebuild of the component, and the documentation site that ships with it. See `REBUILD.md` for the rebuild's design and `/migration` for what changes for a 0.0.x user. #### Known - **Excalidraw's font-subsetting worker runs on the main thread, and an SVG export of text logs one console error.** The worker's URL is resolved from `import.meta.url` at build time, so the bundle carries a `file://` path of the machine that built it. A browser refuses it — `new Worker(…)` from the page raises `SecurityError: Script at 'file:///…/subset-worker.chunk.js' cannot be accessed from origin 'https://…'` — and Excalidraw catches that and falls back, logging `Failed to use workers for subsetting, falling back to the main thread.` once. **Exports are correct**; only the console is noisy and the subsetting is slower than it would be off-thread. Measured on the deployed site, not inferred from the source. Pre-existing since the first build of this rebuild, not new in 1.0.0. The fix is to have webpack emit those chunks under a URL Dash can serve, and it belongs in the next release rather than in a change made under a tag. ### Site — internal traffic is dropped from the read table too (2026-09-01) Consumes `sync/SYNC-1.6.43.md` items 1–3 at template 2b1edd5. Item 1 first, as the drop ordered: its consequence was accruing. #### Fixed - **`record_read` drops internal traffic before it reads any field.** `track_visit` has honoured the network's internal-traffic contract since it existed; the `on_document_read` hook added at the 2.8.0 floor did not. So the hub's health sweep, this site's own link audit and every post-deploy battery were landing in the `reads` table and had become the busiest "vendor" on the board. "Counted nowhere" includes the read table — a host that drops the token from one table and not the other holds half its own contract. Keyed on `ua`, which is what `EVENT_FIELDS` calls it; keyed on `user_agent` it would have been a silent no-op, so the field name is pinned against the resolved package, not against the spec text. Measured both directions: internal-token probe → 0 read rows, real crawler probe → exactly 1, counts printed beside the result. - **The test-client UA pin reads the CODE, not the file.** Its file-scoped form flagged `tests/test_internal_traffic.py`, which drives no client at all — it mentions `.test_client()` in a comment about greps matching comments. Now AST-based, with a non-vacuity guard: the sweep must match at least three files, because a sweep that found nothing and a sweep that swept nothing produce the same green. It sweeps 6 and goes red under mutation. #### Added - **`/healthz` reports `llms_version`.** The payload named `dash_version` and `python` but not the package every floor in this fleet is about, and item 1's acceptance asks each host to compare `EVENT_FIELDS` across its CI-vs-production pair — a comparison this host could not make from outside. Additive and omitted on failure. Adopted by the fleet the same day under this name: it ships as 1.6.44 item 1's eighth `/healthz` key, so this is early adoption rather than a divergence (DIVERGENCES 16). The name was settled before either side shipped, because the template drop was carrying the field as `dimll` and a fleet key with two names is the failure `/healthz`'s shape contract exists to prevent. - Three kit traps in `.claude/CLAUDE.md`, all earned in the item-18 round: which branch Render builds can be measured on a green push by timing (as evidence, not proof); verify the artifact the claim is about and say which one; and assert the corpus is non-empty before trusting any negative. Tests 468 → 470. ### Site — the 1.6.41 remainder, and the caller for the cargo (2026-08-31) Consumes `sync/SYNC-1.6.22-1.6.42.md` item 18 at template 4ac02e0, with the a33ecfe amendment to contract highlight (7). This is the round that closes the seam this fork reported from inside: it had `slim_generated_on()` and nothing called it. #### Added - **`/api` carries a `lastmod`** — the committed extract's `generated` stamp, reaching the sitemap through `api_reference.slim_generated_on()`. `/api` was the one page in a 14-entry sitemap with no lastmod while the extract sat on disk. `/api` and `/changelog` now register the FULL machine record (visibility, tier, lastmod), not just a module `LLMS_DOC`. - **A row-parity pin for `/api`, with a mutation check.** Four mechanisms produce an empty `/api` at 200; a heading pin passes on all four. This one asserts ROWS and row CONTENT across the machine lane, the received HTML, the prerender block inside it, and the component tree React mounts — and a second test breaks the loader to prove the pin can go red. - **A skip link** as the first tab stop, and **short sidebar labels** (`nav:` frontmatter) available per page. - **`tests/test_layout_nesting.py`** — `parse()` returns a LIST, and `children=[hero, parse(...)]` renders the page EMPTY with a green suite (React #31; the prerender reads the markdown, so every machine-lane check stays green). Walk + non-vacuity fixture + registry-derived positive control + source pin. - **`smoke_live.py` gains three checks**: `HEAD /healthz answers what GET answers`, `GITHUB_URL resolves`, and a `/` dedup so a broken home page stops printing three identical failures. #### Fixed - **The battery was checking the wrong hidden paths.** `network_smoke.HIDDEN_DOC_PATHS` still held the template's canary (`/admin/llms.txt`, `/analytics/llms.txt`) — neither is a page here — so it probed two paths that 404 because nothing serves them, a vacuous pass, while never checking the two admin pages this site actually has. Now the real ones, pinned against the registry. - **`scripts/audit_links.py` drove a bare in-process test client.** A bare client sends `Werkzeug/x.y`, which is the crawler lane at the 2.8 floor, so the audit fetched the crawler document for every page and would report this site's own `mark_hidden` admin pages as broken links. Its `AUDIT_UA` was crawler-shaped too. External requests keep that identity; in-process ones now name the browser lane. - The header's identity (`WORDMARK`, `LOGO_ASSET`, `LOGO_STYLE`, `WORDMARK_COLOR`, `WORDMARK_VISIBLE_FROM`) moves to `lib/constants.py`, so `components/header.py` holds no fork content and is byte-identical to the template. - The changelog parser accepts every heading shape the fleet writes — em dash, en dash, no brackets, prose-first, and words where the date goes. This repo's own `## [0.1.0] — unreleased` now reads as a note rather than a date, and `/changelog` omits its lastmod honestly instead of inventing one. Tests 446 → 468. ### Site — the wall comes down, and navigation comes from one registry (2026-08-30) Consumes dash-documentation-boilerplate's `sync/SYNC-1.6.22-1.6.38.md` items 15 and 16 at template 1.6.39 (`519d496`), against the owner's brief `DESIGN-navigation-uniformity-2026-08-30`. Nothing here touches the component half. **Not deployed** — the owner holds the push. #### Changed - **Training crawlers are ALLOWED by default.** `block_ai_training` is off: robots.txt emits no training stanza at all (GPTBot, ClaudeBot and CCBot fall under `User-agent: *` / Allow), and the package's middleware stops answering 403 on the browser document and `/healthz` for them. The wall decided by vendor CLASS what nobody could account for; since the 2.8.0 ledger round every corpus read is a row that can be priced, so the tool is now per-vendor policy — `vendor_policy={"": "block" | "meter"}` for ONE vendor whose rows justify it. Measured on this host's wire 2026-08-30 BEFORE the flip: ClaudeBot and GPTBot both 403 on `/`, 200 on `/llms.txt`, 403 on `/healthz`. In-process AFTER: 200/200/200 for both, and zero `Disallow: /` in robots.txt. Every one of those 403s was the app's own middleware — there is no edge wall in front of this host. - **The sidebar is built from frontmatter, not from a hand-written list.** `components/navbar.py`'s `page_order` and `excluded_links` are DELETED. Sections now come from each page's `category:` ordered by `lib.constants.CATEGORY_ORDER`, and pages within a section by a new `order:` frontmatter field. The reading order the old list encoded is preserved exactly, promoted from page names to four categories: Getting started · Data flow · Appearance · Advanced. - **The network is listed ONCE**, as the top bar's *Other Apps* hover menu, from `lib.network_directory.PRIMARY` — 2plot.ai, 2plot.dev, 2plot.media, piratesbargain.com, ai-agent.buzz, this host removed, labelled by domain. The sidebar's "Pip Components" and "Other Apps I've built" sections are gone, and with them the duplicate 2plot.dev entry that appeared in both that list and Resources. - **Resources is third-party only**: `dmc` and Excalidraw, the upstream project this component wraps. `community.plotly.com` and the duplicate 2plot.dev link are removed. - **The top bar's GitHub icon and JSON-LD `sameAs` share one constant** (`GITHUB_URL`), and the icon points at this repository rather than the profile. The footer's GitHub link is the profile — two different links, each in the right place. - **`/admin/*` is hidden, not blocked.** The startup sidebar tree carries no `/admin/` href at all; a callback fills an Admin section only for `is_admin_user()`. Admin pages never enter search either. - **`/admin/traffic`'s day picker is `dmc.DatePickerInput`**, bounded by the ledger's first and last day with Today / Yesterday / Last 7 days presets — the fleet's no-`dcc`-where-DMC-has-it rule. `pages/home.py` moves off `dcc.Markdown` to the same markdown2dash renderer the docs use. #### Added - **`/changelog`** — this file as a DMC Timeline, and its own `LLMS_DOC`. Linked once, from the sidebar. - **`/api`** — one prop table per component, generated from the installed package's `metadata.json`. `API_PACKAGES = ["dash_excalidraw"]`, so this site documents `DashExcalidraw`'s 38 props without hand-maintaining a table. The header gains a version badge reading the same package. - **A footer** — © {year} Pip Install Python LLC · GitHub profile · Discord · YouTube, every icon named. - **A People section on `/admin/traffic`**, above the crawler tables, with the day's human hits / visitors / sessions / median session and the line that answers the owner's question directly: humans never enter the read ledger, so "(unidentified)" below is the crawler lane with no vendor match, never a person. - **Accessibility**: the sidebar Burger, the search inputs, the ledger's day picker and every footer icon carry names; `CodeHighlightTabs` sets `copyLabel` / `copiedLabel`. - **Auth-tier pages carry a lock in the sidebar** — `/ai-agent` and `/benchmark`. A divergence from template 1.6.38, recorded and filed upward: the template has no auth-tier docs page, so listing one indistinguishably from a public page was never its problem. - **Mobile fit**: code blocks inside a List item, Blockquote or Timeline can no longer widen the document at phone width, and the mobile drawer is `keepMounted` so the hamburger never opens onto an empty panel. - Tests 418 → 445. New: `tests/test_nav_contract.py` (25 pins), `tests/test_excluded_links_hidden.py`, `tests/fixtures/fake_dash_pkg`, and the battery's lane pin. #### Fixed - **The live battery's default User-Agent names the browser lane** (`sync/SYNC-1.6.22-1.6.40.md` item 17, found by muischeduler). At the 2.8.0 floor a User-Agent with no browser engine token is crawler-lane, and `scripts/network_smoke.py`'s default was the bare internal token plus `" network-smoke"` — so every default-UA check was reading the prerendered crawler document, and any browser-shape check would have gone red in CD's verify job the moment it was added. The Chrome/AppleWebKit token now comes FIRST and the internal token after it; `INTERNAL_UA_TOKEN` is a substring match, so the analytics exclusion still holds and the run is still counted nowhere. `CRAWLER_UA` is the other lane and is untouched. `scripts/smoke_live.py` was audited and already had this shape. - **`scripts/smoke_test.py` names the browser lane too** — the same defect by a second road (found on leaflet's first CD run). A backend test client sends NO User-Agent, which at the 2.8.0 floor is the crawler lane, so the harness's "every registered page returns 200" loop was asking the crawler lane about `/admin/control-board` and `/admin/traffic` — pages that are `mark_hidden` and therefore CORRECTLY 404 there. Reproduced on this tree: `python scripts/smoke_test.py` exited 1 with those two as the only failures, which would have gone red in CI's `compat-matrix` job and taken the deploy with it. Every request the harness makes now carries a browser-lane UA, and the crawler lane is asserted explicitly rather than assumed — admin paths must 404 to a crawler — so naming the browser lane cannot mask the inverse regression of a hidden page becoming public. 56/56 checks, exit 0. - **`/api` no longer depends on a gitignored build artifact.** `dash_excalidraw/metadata.json` is a `dash-generate-components` byproduct: gitignored on purpose, and `scripts/check_release.py` asserts it is absent from the built wheel. So it exists only on a machine that has run `npm run build` — never in a CI checkout, never in the production image. Reading it alone made `/api` document 38 props on the author's laptop and nothing anywhere else. `lib/api_reference.py` now prefers `metadata.json` when present and falls back to the generated component class's docstring, which is tracked, ships in the wheel, and carries the same catalogue in Dash's standard "Keyword arguments:" format. Same 38 props either way. Superseded within the day by template 1.6.41's three-source loader, taken as cargo: `metadata.json` → the committed `api_metadata.json` extract (`scripts/build_api_metadata.py`, 11 KB, tracked) → the docstrings. All three roads produce the same 38 props here. ### Site — the ledger row, and `release` becomes the deploy branch (2026-08-29) Consumes dash-documentation-boilerplate's `sync/SYNC-1.6.22-1.6.35.md` items 12 and 13 at template 1.6.35 (`4c63992`). Nothing here touches the component half. #### Changed - **dimll floor 2.7.1 → 2.8.0**, in all four encodings the number lives in: `requirements.txt` (the flask line plus the three commented backend lines), `run.py`'s `LLMS_PKG_FLOOR` and its boot diagnosis, and `ci.yml`'s two asserts. Editing the requirements line IS the Docker cache bust; a `>=` floor can never pull a new release through a cache hit. - **There is ONE classifier.** `lib/analytics_tracker.py` carried its own User-Agent lists for a year. They filed ClaudeBot — Anthropic's *training* crawler — under "search", still named the retired `anthropic-ai` / `claude-web` tokens, and counted every UA-less or library client (`httpx`, `Go-http-client`) as a person. The lists are gone: `is_bot` and `detect_bot_type` keep their names and signatures for callers and delegate to `dash_improve_my_llms.classify()`, which is the same registry `robots.txt` is rendered from — so what this site SAYS about a vendor and what it COUNTS now agree. `track_visit` classifies exactly once, *after* the real client IP is resolved, so `verified` is computed against the client rather than the proxy. Crawler rows gain `vendor_key`, `vendor_class`, `verified` and `lane`; human rows are byte-identical to before. - **REPORTING CONSEQUENCE, expected and not a regression:** `human_hits` DROPS and `bot_hits` RISES on adoption day, because UA-less and library clients move from the human lane to the crawler lane. That is the number becoming true. The hub's day-over-day view will show the step. - **Render deploys `release`, and only CD writes `release`.** `.github/workflows/cd.yml`'s `deploy` job no longer POSTs a Render deploy hook; it fast-forward-pushes the run's own sha to `refs/heads/release` after the CI matrix is green, under a job-level `contents: write` grant (the workflow stays `contents: read`). The checkout is `fetch-depth: 0` — a shallow HEAD pushed onto an EXISTING `release` is rejected as non-fast-forward, which a fork does not discover until its SECOND promote. `render.yaml` declares `branch: release`. A push to `main` is now a candidate, not a deploy. **The repository's deploy-hook secret is inert and safe to delete.** - **`verify` gains a `/healthz build == github.sha` assertion of its own**, and its `if:` is now the template's verbatim `needs.deploy.result == 'success'` (was `always() && needs.deploy.result == 'success'` — the two are equivalent). This fork's divergence 5 is **retired by convergence**: template 1.6.35 adopted the stricter gate after run 33262495272 showed the permissive form reporting GREEN against the previous build on a failed promote — the same failure this fork measured on 2026-08-21. #### Added - **The read ledger.** `run.py` registers `on_document_read( tracker.record_read)` once, next to `add_llms_routes`. Every corpus document dash-improve-my-llms serves now lands as a row in a `reads` table in the SAME analytics file — same buffer, lock, flush cadence and retention as `visits` — carrying tier, lane, vendor, verified, policy, verdict, status and bytes. `client_ip` is dropped unless `ANALYTICS_KEEP_CLIENT_IP=1`. `reads` is a second table joined by the rollup, never summed into `human_hits` / `bot_hits` / `pages`. - **Rollup v4, additive.** `lib/traffic_rollup.py` gains `load_reads` and `vendor_rows`; `daily_rollup` emits `vendors[]` (one row per `(key, verified, policy)`, null key kept, sorted by hits desc, capped at 40, all seven tier keys always) and `reads` — but ONLY on a day that has reads, so a host below the floor and a quiet day are indistinguishable by absence, which is the truthful state of both. Every v3 key is byte-identical. - **`/admin/traffic`** (`pages/traffic.py`) — this host's own ledger behind the control board's exact gate, failing CLOSED without Clerk and `mark_hidden` at import. Vendor × day, vendor → tier for the picked day, top paths per vendor, and the v3 headline numbers for the same day. Plain tables, no charts, no interval callback; the day dropdown is the only control. The page says in words what `verified` means: `n/a` is a vendor publishing no IP ranges — Anthropic publishes none, so ClaudeBot is ALWAYS `n/a` here, and that is a property of the vendor, not a defect on this host. - **`DIVERGENCES.md` gains a `posture` fence** declaring `deploy: release-branch`. Only that key: the rest of the 1.6.30 posture item is not adopted here, and declaring `ai_bots` / `healthz` from the tree rather than from the wire would be the aging copy the fence exists to kill. - Tests 380 → 418. New: `tests/test_analytics_classifier.py` and `tests/test_traffic_rollup_v4.py` (the spec's block cargo, byte-verbatim), `tests/test_read_ledger.py`, `tests/test_traffic_page.py` and `tests/test_cd_promotes_release.py`. #### Fixed - **`tests/test_proxy_scheme.py` names the browser lane.** Its end-to-end `twitter:url` probe sent no User-Agent, and at the 2.8.0 floor an absent UA is the crawler lane — the crawler document has no `twitter:url` at all, so the test failed on "no tag" without saying anything about the scheme. It sends `BROWSER_UA` now. This is a "satellites copy this verbatim" file and the red hit every Flask fork in the fleet; either lane can be the one you did not mean to test. ### Site — one fleet Python, and the live tools grow their contracts (2026-08-26) Consumes dash-documentation-boilerplate's `sync/SYNC-1.6.22-1.6.29.md` items 5 and 6 at template 1.6.29 (`5589318`), plus the fork drop's two addenda. Nothing here touches the component half. #### Changed - **The image, the workflows and `/healthz` now name ONE Python: 3.14.** The production image was `python:3.12-slim`; the site-lane CI matrix said 3.12; nothing on the wire could contradict either, because `/healthz` carried no `python` field at all. It does now (`platform.python_version()`, one builder for both backends), and `scripts/network_smoke.py` gained the `python_matches_declared` check that holds the SERVING interpreter to the Dockerfile's `FROM` minor. A missing field is NOT-ADOPTED rather than not-applicable: emojimart's image moved to 3.14 through dependabot alone, so the cheap half of the detect passed while the expensive half failed invisibly. - **The site's compat window is 3.14 / 3.13 / 3.12** (was 3.12 / 3.13 with a 3.10 floor leg). The package's own 3.9-3.13 claim is untouched — it is measured by `package-python-range`, against the built wheel, which is where `requires-python` is actually a promise. `render.yaml` needed no change and is now pinned that way: on a `runtime: docker` service `PYTHON_VERSION` must be ABSENT, because nothing reads it there and a string that looks like the platform's setting and can never be true is the same defect class arriving through its own fix. - **`scripts/smoke_live.py` is byte-current with template 1.6.29**, which brings two behaviours this fork lacked: the auth-wiring probe (`POST /api/auth/{session,signout}` must not answer 0/404/405 when the served shell carries the Clerk bootstrap — the flexlayout defect, where `register()` runs without `configure_app(app)` and every server render reads signed-out while the UI looks signed in), and a `wake()` that tolerates a legacy `fetch` stub instead of taking a fork's whole suite down. Measured against production before shipping: the shell carries the bootstrap, `/api/auth/session` answers 401 and `/api/auth/signout` 200, so the probe is armed here and green. #### Added - **`tests/test_python_version.py`** — the encodings-agreement pins, adapted for a repo that carries two Pythons legitimately. Scoped BY JOB NAME rather than by file, because the template's reference greps a whole workflow and this is the first repo in the fleet with a lane that file explicitly disclaims; `test_every_job_declaring_a_python_is_classified` is the guard on the guard, so a job nobody classified fails loudly instead of going quietly unread. Workflows are hand-parsed with comments stripped — not via PyYAML, which this site never declares (it arrives only as a transitive of `python-frontmatter`, and a pin that dies of ImportError the day an upstream swaps YAML libraries has stopped pinning). - **An SSL context on `scripts/network_smoke.py`'s `urlopen`**, with a source pin beside `smoke_live.py`'s. This makes the battery's trust store a declared dependency (`certifi`, already required) rather than whatever CA bundle the running interpreter was built against. Stated plainly because the drop's rationale was stronger: the "reads a healthy host as down from a Mac" symptom did NOT reproduce on this seat — measured both ways against production, 10/10 either way — so this ships as parity with `smoke_live.py`, not as a fix for an observed outage. The template's copy has the same gap; filed upward with the correction attached. - `tests/test_smoke_live.py` gains the legacy-stub guard, and its foreign-canonical stub now DERIVES the rewrite host from `BASE_URL` instead of spelling it — a literal that happened to be right on this fork is luck, not a property, and the vacuous-pass mode it invites is what the template's 1.6.8 hardening exists for. #### Divergences recorded - **8** — `ci.yml`'s two Pythons: the site lane is the fleet's, the package lane is `pyproject.toml`'s, and a sync must not "restore" the latter. - **9** — `network_smoke.py`'s SSL context, which is ahead of the template rather than divergent from it; the entry retires when the template adopts it. ### Site — .claude kit adoption (2026-08-25) Consumes dash-documentation-boilerplate's `sync/SYNC-1.6.10-1.6.16.md` and `sync/SYNC-1.6.17-1.6.21.md` at template 1.6.23. Most of the first spec was already satisfied by the floor round; what is new is the shipped development kit, the machine-readable divergence fence, and four smaller ports. #### Added - **`.claude/` is shipped, not ignored.** This repo blanket-ignored the whole folder from its first commit, so the network's behavioral contract, its skills and its settings stayed local to one machine and propagated to nobody who cloned it. `.gitignore` becomes an allow-list (`.claude/*` plus `!CLAUDE.md`, `!settings.json`, `!skills/`); everything else — `agents/`, `rules/`, `scripts/`, `tasks/`, session scratch, `settings.local.json` — stays local. `.claude/CLAUDE.md` keeps this repo's own guide (rewritten: it still described an `app.py` demo and a `pages/` full of showcase files, neither of which has existed since the docs site landed) and gains the template's contract and verification-traps sections byte-verbatim. - **`DIVERGENCES.md`**, with seven recorded deliberate differences and the `byte-owned` machine fence the fleet's fan-out honours. The fence is **empty by decision**: this repo carries all four `sync-verbatim` paths byte-verbatim and intends to keep receiving them mechanically. - **`tests/test_claude_kit.py`**, byte-verbatim from the template — pins the kit shippable, case-correct, and pointed at *this* host rather than the template's. - **CI asserts Docker's own health verdict** (`docker inspect .State.Health.Status`), failing on `none`. The external curl proves the app answers; it says nothing about the HEALTHCHECK instruction, which is what an orchestrator actually reads — emojimart shipped a broken probe silently while every external check stayed green. - Source pins for two absences no rendered output can show: every `urlopen` in `scripts/smoke_live.py` carries `context=SSL_CONTEXT`, and `pages/home.py` runs `substitute_versions` over `home.md`. #### Changed - **`X402-SYNC-REPORT.md` is untracked** (kept on disk). Session working documents are local by convention network-wide; two public fleet repos were caught tracking theirs. `DEPLOY-READINESS.md` deliberately stays tracked — it is an owner deliverable and names no values (DIVERGENCES §4). - **The auth-gate teaser demo points at this site.** `lib/auth_demos.py` still carried the template's `/examples/visualization` -> `docs.data-visualization.basic_chart` entry: no such page, no such module. `build_demo` swallows import errors by design and the endpoint was never a page here, so not even its warning ever fired — every gate card on the site quietly rendered the demo-less variant. Rekeyed to `/ai-agent` (one of the two pages this site hard-gates in frontmatter) showing the basic canvas. Deliberately **not** the AI agent module: that page's buttons call paid thinking models, and a live model call inside an unauthenticated sign-in card is an open invoice. - **The Dockerfile defaults the port at the point of use** — `${PORT:-8050}` in both `CMD` and `HEALTHCHECK`. The `ENV` default covers *unset*, not *set-empty*; a bare `${PORT}` collapses the bind to `"0.0.0.0:"` and points the probe at `http://localhost:/healthz`. - **CD is sized for the worst build**: the build-match wait goes 60 → 100 iterations and the job timeout 20 → 30 minutes, because a floor bump busts the pip cache by design and this pipeline's most important deploy is therefore Render's slowest. A missing deploy hook now emits `::warning` rather than `::notice` — the quiet notice is why "nothing deployed at all" took a whole run to see on dash-email. - **`pages/markdown.py` and `lib/page_visibility.py` regain byte-identity with the template**, which adds `published_name()`: the site brand is what a root page publishes to agents, so the llms preamble and the injected prerender header agree and 2.7.0's H1 dedup can fire. A no-op here (no docs page registers `/`) and taken anyway, to remove the drift point. - **`lib/gate_layouts.py` keeps "and the AI assistant"**, against the template's 1.6.16 retirement. That fix's premise — no fork wires one — is false here: `docs/ai-agent` is a real page at `tier: auth`. Ported as the item's contract (*the gate card promises only what ships*) with a test that goes red if the page's tier ever opens. ### Site — floor round (2026-08-23) Moves to `dash-improve-my-llms >= 2.7.1` and syncs four template fixes from dash-documentation-boilerplate 1.6.9-1.6.13. #### Changed - **dimll floor 2.6.1 → 2.7.1**, in all six places it is encoded: requirements.txt (the pin and the three commented backend extras), run.py's `LLMS_PKG_FLOOR` and its boot message, and ci.yml's extras install plus both version asserts. 2.7.0 dedups the prerender H1 and the home footer's doubled `/llms.txt` link, and hardens the idempotency probe so a page that merely MENTIONS the marker keeps its prerender; 2.7.1 adds the llms.txt v2 discovery relations and Link headers, the `Accept: text/plain` ramp, and the representation digest. **Editing the requirements line is the Docker cache bust** — that layer re-runs only on a byte change, so a `>=` floor can never pull a newer release through a cache hit. - **`/healthz` is built per request, from one payload, on every backend.** It was a snapshot closed over at registration — harmless while every field was static and wrong the moment one is not. FastAPI built its own payload *without* `build`, which is the exact field cd.yml's build-match wait polls for, so a FastAPI deploy would have verified whichever release happened to be serving. The payload gains `app` (`SATELLITE_APP_KEY`, else `"unknown"`) and, on dimll >= 2.7.0, `geo` `{configured, denied, resolved}` — counts and flags only, never the denylist's country codes, and omitted rather than error-flagged on older packages. - **`_expand_source_directives` is fence-aware.** A `.. source::` inside a fenced block is documentation showing the syntax, not a directive; expanding it injected a fence inside the open fence, closed it early, and rendered the inlined Python as markdown — every `# comment` becoming an `

`. Latent here (no doc teaches the directive yet) and fixed before it could bite. - **Dependabot pip version-updates restricted** to `dash*` / `plotly*` / `markdown2dash`. Without the allow-list it proposes floor-raises for every requirement, and those floors encode minimum-compatibility knowledge — the gunicorn floor *is* the CVE fact. Security updates are unaffected; they arrive through a separate channel. #### Fixed - **The noscript block carried an `

`, so every page served two.** Crawlers run no JavaScript but do parse `noscript`, making it a second site-wide h1 competing with each page's own. Found by the every-page structure pin the moment it was ported. The block now starts at h2. #### Added - The every-page structure pin: every non-admin page serves exactly one `

` to a generic client (comments stripped first), no duplicate llms.txt links in the prerender footer, and home carries the root link exactly once. - Four healthz contract tests, the fence-awareness test, and the noscript pin. - The Dockerfile's cache-semantics block, plus `curl` and a `$PORT`-aware HEALTHCHECK. ### Site — round-2 pass (2026-08-22) Follow-ups from the gate-wave review, an outside SEO audit, and the dash-improve-my-llms 2.6.1 pickup. #### Fixed - **The home link had no accessible name on phones.** Below 576px the wordmark is `display: none` (that is what `visibleFrom` compiles to), and a display:none subtree is removed from the accessibility tree entirely — so with a decorative logo beside it the branded header link announced as just "link", with nothing saying where it goes. The gate-wave report claimed `visibleFrom` "stays in the accessibility tree"; **that was wrong**, and the report has been corrected. The anchor now carries a permanent `aria-label` and the logo is explicitly decorative (`alt=""`) so the two do not compete for the accessible name — template 1.6.6's pattern. - **The meta description was 270 characters.** Google truncates around 155-160 and, for a description it judges unrepresentative, rewrites the snippet from page text — so an over-long one forfeits the snippet rather than shortening it. Now 153, in `lib/constants.SITE_DESCRIPTION`, with index.html's JSON-LD copy kept in step. - **The meta keywords still described the template.** The tag shipped naming Dash Mantine Components, markdown docs and developer tools — the one tag that states outright what a site is about never once mentioned Excalidraw. Replaced with terms for the component. #### Changed - **`lib/network_directory.py` re-copied verbatim from the boilerplate.** Template 1.6.5 added `excalidraw.2plot.dev` and `modelviewer.2plot.dev` to the canonical list now that both are live. `test_this_host_is_queued_for_registration` fired on the re-copy exactly as it was designed to, and is replaced by two tests that pin the steady state: the self-filter removes exactly one row (which proves the spelling), and this host's row exists at the source (which a healthy self-filter would otherwise hide). - **dimll floor 2.6.0 → 2.6.1**, in requirements (including the commented backend extras), `run.py`'s boot floor and its message, and CI's two version fingerprints. 2.6.1 makes the universal prerender visible to non-JS consumers: below it the injected block carries a literal `hidden` attribute, so every visibility-respecting reader saw "Loading..." and nothing else. A `>=2.6.0` build resolves 2.6.1 today, but that is resolution luck rather than a guarantee — the floor is stated where the guarantee is. Verified by downgrading: on 2.6.0 the new generic-lane test fails on the `hidden` attribute and the boot floor refuses to start. ### Site — gate-wave pass (2026-08-21) The 2plot network's gate/reporter/SEO sync, from dash-documentation-boilerplate 1.6.4, plus the deployment groundwork this host had never had. **The documentation site is not affected in anything a visitor can see: it ships DARK** (`PAGE_DEFAULT_TIER=public`), which means the gate plumbing goes live and changes nothing. Everything here is the site under `run.py`; the `dash_excalidraw` package is untouched apart from one metadata fix. #### Fixed — mobile - **The home page scrolled sideways on phones.** The prop-mapping table is min-content sized, so with `overflow: visible` it burst out of its column and dragged the document with it: measured at 414px, the table rendered 471px inside a 318px container and the page scrolled 105px horizontally, so every paragraph could be swiped off-screen. Markdown tables now scroll inside their own box (`display:block` + `width:max-content` + `max-width:100%` + `overflow-x:auto`) — a no-op above the container width, so desktop is unchanged. `dmc.Table` (which /file-uploads renders, and which has its own scroll container) is explicitly excluded. - **/ui-options scrolled sideways too**, by 15px: a Switch labelled `canvasActions.changeViewBackgroundColor` — a dotted identifier with no break opportunity — rendered 309px wide in a 250px box. Control labels in the docs bodies now use `overflow-wrap: anywhere`. - **All fifteen pages now measure zero horizontal overflow at 414px.** - **Three stylesheet rules targeted Mantine's internal hashed class names** (`.m_46b77525`, `.m_5caae85b`, `.m_9cdde9a`). Those hashes are private, version-unstable build artifacts. Audited against DMC 2.8: `.m_5caae85b` had already gone dead (zero occurrences in the bundle), and `.m_9cdde9a` was putting a stray `margin-top: 15px` on the AppShell aside while re-declaring width, transform and z-index that Mantine already sets. The header-Select rule was rewritten against a stable selector; the other two are gone. This is the failure 2plot_leaflet recorded after a `.m_b8a05bbd` rule — the Drawer content — silently overrode its drawer's docking styles and left that host's mobile navigation floating. A test now fails on any `.m_*` selector in any stylesheet. - **The header wordmark overflowed the row on phones.** `dash-excalidraw` is a long mark to sit beside a burger, a 36px logo, a search control and the theme toggle. It is now `visibleFrom="xs"` — hidden below 576px (36em), which covers every phone in portrait. Measured at the boundary: hidden at 360/414/575px, shown from 576px. `visibleFrom` renders a CSS class rather than dropping the component, so the element stays in the DOM: the site's name is still in the accessibility tree via the logo's `alt`, and `assets/text_animation.js` still finds `#dash-docs-title` to type into. #### Fixed — the first CI run (round 2) The first run of the rewritten workflows lost nine checks. Every one was in the CI configuration; none was in the site. The four pytest legs, lint, and the Docker build-boot-battery job all passed first time. - **`scripts/smoke_test.py` did not exist** — six `docs-compat` legs called it. Same class as `check_release.py`: the job and its script were both leaflet's. Ported; it node-syntax-checks all 23 inline clientside callbacks and all four asset JS files, which no pytest can reach. - **The wheel's packaging-leak check was fooled by its own working directory.** `importlib.util.find_spec("lib")` ran in a heredoc whose cwd was the repo root, and Python puts the cwd on `sys.path` for a stdin script — so it found the repo's own directories and failed on a clean wheel. Now a `zipfile` scan of the artifact, plus a clean-venv import run from `/tmp`. - **The docs-compat matrix tested Dash 4.1.0, which this site cannot run on.** `run.py` passes `backend=` to the Dash constructor and 4.1.0 rejects it during construction. Measured: 4.1.0 cannot boot; 4.2.0, 4.3.0 and 4.4.1 each pass 48/48. The floor is 4.2.0 and the matrix now says so. - **`requirements.txt` never carried the `# COMPAT-MATRIX: dash` marker** the matrix strips, so the pin was silently reinstated on every leg — a green matrix testing one Dash version three times. - **A failed CI run produced a misleading production failure.** With `deploy` skipped, `verify the live site` still ran and failed against production. Now gated on the deploy having actually succeeded. `tests/test_config.py` gains three tests for the class rather than the instances: every script a workflow runs must exist, no workflow may name another repo's artifacts in live YAML, and the dash pin must keep its matrix marker. #### Fixed — things that would have broken the first deploy - **The site was on a branch Render does not deploy.** `main` held the initial component commit and nothing else; the entire documentation site lived on `feat/excalidraw-0.18.1`. `main` is now fast-forwarded onto it — no commit rewritten, squashed or dropped. - **`.github/workflows/cd.yml` deployed and smoke-tested `leaflet.2plot.dev`.** It was a copy of that repo's file and had never run. Rewritten from the template, which also carries the fix for CD verifying the *previous* release whenever the deploy hook is unset — the fleet's default configuration. - **`.github/workflows/ci.yml` and `release.yml` were also leaflet's**: package jobs importing `dash_leaflet2`, an image tagged `dash-leaflet2-docs`, flake8 pointed at a `usage.py` this repo lacks, a missing `scripts/check_release.py`, and `dash-leaflet2` as the PyPI trusted-publishing target. - **The Dockerfile bound a hardcoded port 8550**, which Render (which assigns `$PORT`) cannot health-check, and installed nodejs + npm to build a bundle that is committed. Rewritten to the fleet shape: python 3.12-slim, binds `$PORT`, `WEB_CONCURRENCY`, a 120s timeout for the model calls, no Node. - **`.env.example` documented `CLERK_SATELLITE_DOMAIN=excalidraw.2plot.dev`.** Every `*.2plot.dev` docs host is an allowed *subdomain* of the one `2plot.dev` satellite; the per-host spelling resolves to NXDOMAIN and hangs sign-in with no error. #### Fixed — SEO and identity regressions - `twitter:card` had been deleted from `templates/index.html`. Dash declares it with `property=` and Twitter's parser reads only `name=`, so no scraper could see a card type at all. Restored. - Three icon links (96/192/512) had been dropped from the head, so it could not agree with the crawler head. Restored. - `msapplication-TileColor` still carried the template's teal against a violet `theme-color`. - The noscript block advertised `/getting-started/llms.txt`, a template page this site does not have. #### Added - The interactive gate, **dark**: `lib/gate_layouts.py`, `lib/access.py`'s two-axis resolution, `lib/page_visibility.py` and the `/admin/control-board` page, `lib/agent_key.py` (`/api/agent-key`), `assets/auth_gate.*`. - `configure_seo` with this site's own seven-icon set, social card and publisher/`sameAs`; `SoftwareApplication` on the home page; and truthful `lastmod` on all fourteen docs, taken from each file's real last-commit date via `git log` — never invented, never from a file mtime. - `lib/versions.py`, so prose can write `{{VERSION:}}` instead of a number that goes stale. - `scripts/check_release.py` and `scripts/make_favicons.py`. - `DEPLOY-READINESS.md` (the owner-side deploy checklist) and `X402-SYNC-REPORT.md` (what this pass did, measured). #### Changed - **Vendored `dash-clerk-auth` 1.0.0 → 1.0.5**, from the hook repo's `dist/` and admitted only on sha256 `a2f9062e…b74f3`. 1.0.5 is the release that reconciles the *return trip*: landing back on a gated page after signing in on the primary used to show the gate card until a manual refresh. - **Security floors**: `clerk-backend-api>=7.0.0,<8` and `cryptography>=50.0.0`. The old SDK cap held `cryptography` below the fixes for GHSA-537c-gmf6-5ccf and PYSEC-2026-3552/3553/3554; all four now audit clean. - Floors raised: `dash-improve-my-llms[flask]>=2.6.0` (honest sitemap `lastmod`, icon autodiscovery), `dash-mantine-components>=2.8.0` (below it the mobile drawer renders as a floating card), `plotly>=6.9.0`. - `lib/satellite_reporter.py` is now **byte-identical** to the template's — which is why `run.py` claims `SATELLITE_APP_KEY=excalidraw` via `os.environ.setdefault` before any hub-facing import. Without that, an unset variable would file this site's traffic under the template's row. - `/healthz` reports `build` (the running instance's commit) alongside the existing `app`, so CD can verify the artifact it shipped. - `render.yaml` fully authored for Docker + the 1 GB `/var/data` disk, and deliberately declares **no** env-group-owned variable — a service-level copy would shadow the group and mask future edits. - `dash_excalidraw/package-info.json` advertised `@excalidraw/excalidraw ^0.17.6` while the bundle is built from 0.18.1. ### Security - **Repository history starts clean.** The project had never been committed to any git repository. Before the first commit, the live `ANTHROPIC_API_KEY` and `GEMINI_API_KEY` that lived in the untracked `.env` were rotated at their providers, `.env.example` was authored with names only, and the first commit was gated on three checks: `.env` absent from the staged set, a secret-pattern scan over every staged file, and a review of the staged tree for build directories. No key has ever entered this history. - **`dash_excalidraw/dash_excalidraw.js` contains a `AIzaSy…` string, and that is expected.** Secret scanners pattern-match it as a Google API key. It starts `AIzaSyAd15pYlMci_` (truncated here on purpose, so this file does not itself become a second scanner finding) and appears three times inside the `VITE_APP_FIREBASE_CONFIG` literal that upstream Excalidraw bakes into its own published `dist/` (`authDomain: excalidraw-room-persistence.firebaseapp.com`). It belongs to the Excalidraw project, not to this one, and a Firebase **Web** API key is a public client-side identifier by design — access is enforced by Firebase Security Rules, not by keeping the key secret. It is bundled verbatim by webpack from `node_modules/@excalidraw/excalidraw/dist/`, so any finding against it is **dismissed deliberately** as a third-party public identifier. **Do not re-litigate this**, and do not "fix" it by stripping the string — that would fork upstream's bundle. Note that upstream's *development* builds carry a second such key (`AIzaSyCMkxA60XIW8Kbq…`); webpack's production build does not include it. Measured on the first push (2026-08-08): GitHub push protection did **not** block it. Treat that as unverified rather than as proof the string is ignorable — enable Secret scanning + Push protection under Settings → Advanced Security, dismiss the resulting alert as a false positive, and expect a future bundle-touching push to need an explicit bypass. ### Changed - `.gitignore`: `.claude/` and `.idea/` are now ignored wholesale; the built bundle `dash_excalidraw/dash_excalidraw.js` is now **tracked** rather than ignored (the release gate reads its commit timestamp, and tracking keeps `pip install git+…` working without npm); `dash_excalidraw/metadata.json`, a `dash-generate-components` byproduct that must not ship in the wheel, is now ignored. ### Added - `.env.example` documenting `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` and the `GOOGLE_API_KEY` fallback, read out of `pages/ai_agent.py` rather than out of `.env`. Nothing in the showcase requires a key; every AI provider degrades to a disabled state when its key is absent. --- # Collaboration > Drive the collaborator UI and live cursors from Python — the wrapper exposes the knobs, you bring the transport. --- ### Overview The wrapper does not ship a transport layer, but it exposes the knobs: `isCollaborating` toggles the collaborator UI, and `appState.collaborators` can be driven via the updateScene command. ### Live demo ### Source ```python # File: docs/collaboration/collaboration.py """Collaboration: isCollaborating + appState.collaborators scaffolding.""" import uuid import dash_mantine_components as dmc from dash import Input, Output, callback from dash_excalidraw import DashExcalidraw from docs._shared import canvas_frame, code_block, sync_canvas_theme sync_canvas_theme("collaboration-canvas") CODE = """ DashExcalidraw( id='canvas', isCollaborating=True, ) # Feed collaborators via an updateScene command: {'id': ..., 'type': 'updateScene', 'payload': { 'collaborators': { 'user-1': { 'username': 'Alice', 'color': {'background': '#ff6b6b', 'stroke': '#c92a2a'}, 'pointer': {'x': 300, 'y': 240, 'tool': 'laser'}, }, }, }} """ component = dmc.Stack( gap="md", children=[ dmc.Alert( color="blue", variant="light", children="This example only simulates a single fake cursor from a timer — " "hook it up to a real backend (Socket.IO, Firestore, Liveblocks, ...) " "to make it collaborative.", ), code_block(CODE), dmc.Group( [ dmc.Switch( id="collab-switch", checked=True, label="isCollaborating", size="md", ), dmc.Button( "Simulate Alice's cursor", id="collab-simulate-btn", variant="light", ), ] ), canvas_frame( DashExcalidraw( id="collaboration-canvas", height="560px", isCollaborating=True, ) ), ], ) @callback( Output("collaboration-canvas", "isCollaborating"), Input("collab-switch", "checked"), ) def _toggle(checked): return bool(checked) @callback( Output("collaboration-canvas", "command"), Input("collab-simulate-btn", "n_clicks"), prevent_initial_call=True, ) def _simulate(n): x = 200 + (n or 0) * 40 return { "id": f"collab-{uuid.uuid4()}", "type": "updateScene", "payload": { "appState": { "collaborators": { "user-alice": { "username": "Alice", "color": { "background": "#ff6b6b", "stroke": "#c92a2a", }, "pointer": {"x": x, "y": 260, "tool": "laser"}, } } } }, } ``` :defaultExpanded: false :withExpandedButton: true --- *Source: /collaboration* --- # Command dispatch > Call Excalidraw's imperative API from Python through a JSON-safe command prop dispatched once per id. --- ### Overview Every imperative API the upstream Excalidraw exposes is callable from Python as a `command` prop: a dict with `id`, `type`, and `payload`. The component dispatches once per unique id, then clears the prop so React re-renders don't re-fire. ### The twelve command types | `type` | Payload | Notes | |:-------|:--------|:------| | `updateScene` | `{elements?, appState?, collaborators?, captureUpdate?}` | See history, below | | `addFiles` | A **list** of `{id, mimeType, dataURL, created}` | Raw passthrough | | `replaceFiles` | A **map** `{fileId: {dataURL, mimeType?}}` | Stores the new bytes under a fresh id and repoints the elements | | `resetScene` | `{}` | | | `scrollToContent` | `{target?, opts?}` | | | `setActiveTool` | `{type: "selection"}`, `{type: "rectangle"}`, … | Defaults to `selection` | | `setToast` | `{message, duration?}`, or `None` to clear | | | `toggleSidebar` | `{name, tab?, force?}` | `name` is the sidebar — Excalidraw's built-in one is `"default"`; `"library"` and `"search"` are `tab`s inside it. Naming a tab as the sidebar does nothing at all. | | `updateLibrary` | `{libraryItems, merge?}` | | | `exportToSvg` | Export options | Replies on `lastExport` | | `exportToBlob` | Export options, `{mimeType?}` | Replies on `lastExport` | | `exportToCanvas` | Export options, `{mimeType?}` | Replies on `lastExport` | `addFiles` and `replaceFiles` both reach Excalidraw's `addFiles`, but they are not interchangeable. Use `replaceFiles` to swap an existing file's bytes — it takes the id-keyed map, fills `created` and `mimeType` for you, and skips malformed entries; that is the shape [File uploads](/file-uploads) uses to trade base64 for URLs. **It does not overwrite, because Excalidraw cannot.** `api.addFiles` with an id the store already holds is a silent no-op — measured in a browser: add `x` inline, add `x` again with a URL, read `getFiles()`, and it is still the inline one. There is no `removeFiles`, and `updateScene({files})` is ignored. So `replaceFiles` stores the new bytes under a **new** id and repoints every element that referenced the old one. The orphaned entry cannot be deleted, but nothing references it and `externalizedSerializedData` strips it anyway. Until 2026-09-12 this command claimed the overwrite and silently did nothing, which is why /file-uploads' GIF auto-embed never fired: that page waits for a file whose `dataURL` has become a URL, and there never was one. Use `addFiles` only when you need the raw Excalidraw `BinaryFileData` list, including fields `replaceFiles` would drop. It is a straight passthrough, so the list you send is the list Excalidraw receives: **you supply `created` and `mimeType` yourself**, and an entry missing either is not an error — Excalidraw simply ignores it, so a malformed `addFiles` payload is a silent no-op rather than a visible failure. ```python # replaceFiles — id-keyed map; created/mimeType filled for you {"id": cmd_id, "type": "replaceFiles", "payload": {file_id: {"dataURL": "https://cdn.example.com/a.png"}}} # addFiles — raw BinaryFileData list; every field is yours to supply {"id": cmd_id, "type": "addFiles", "payload": [{"id": file_id, "mimeType": "image/png", "dataURL": "data:image/png;base64,…", "created": 1757376000000}]} ``` ### Scene pushes and undo history Excalidraw `0.18` replaced `commitToHistory` with `captureUpdate`, **and changed what the default means**. `0.17` left undo history untouched when no flag was given; `0.18` defaults to folding a programmatic push into the *next* captured action, so a user's first Ctrl+Z after your `updateScene` would also roll back their own previous edit. Nothing errors and nothing warns. This wrapper therefore defaults `captureUpdate` to `IMMEDIATELY`: a dispatched scene push is a deliberate edit and undoes as one discrete step. Override it per command: ```python { "id": str(uuid.uuid4()), "type": "updateScene", "payload": { "elements": elements, "captureUpdate": "NEVER", # or "IMMEDIATELY" (default), "EVENTUALLY" }, } ``` | `captureUpdate` | Effect on undo history | |:----------------|:-----------------------| | `IMMEDIATELY` | *(default)* The push is its own undo step | | `NEVER` | The push is not recorded; Ctrl+Z skips past it | | `EVENTUALLY` | Folded into the next captured action — Excalidraw's own `0.18` default | Two guardrails worth knowing. Passing the removed `commitToHistory` still works: it is translated (`True` → `IMMEDIATELY`, `False` → `NEVER`) and logs a one-time console warning telling you to switch. And an unrecognised `captureUpdate` value is **not** accepted silently — it warns and falls back to `IMMEDIATELY`, because a typo that looked like it took effect is the worse failure. ### Live demo ### Source ```python # File: docs/commands/commands.py """Command dispatch: drive Excalidraw imperatively from Python.""" from __future__ import annotations import time import uuid import dash import dash_mantine_components as dmc from dash import Input, Output, State, callback, no_update from dash_excalidraw import DashExcalidraw from docs._shared import canvas_frame, code_block, sync_canvas_theme sync_canvas_theme("commands-canvas") CODE = """ @callback( Output('canvas', 'command'), Input('btn-rect', 'n_clicks'), prevent_initial_call=True, ) def pick_rectangle(_): return { 'id': str(uuid.uuid4()), 'type': 'setActiveTool', 'payload': {'type': 'rectangle'}, } """ def _btn(btn_id: str, label: str, color: str = "indigo") -> dmc.Button: return dmc.Button(label, id=btn_id, color=color, variant="light", size="sm") component = dmc.Stack( gap="md", children=[ code_block(CODE), dmc.Paper( withBorder=True, p="md", radius="md", children=dmc.Stack( gap="sm", children=[ dmc.Text("Scene", size="sm", fw=600, c="dimmed"), dmc.Group( [ _btn("cmd-update", "updateScene (seed)"), _btn("cmd-reset", "resetScene", color="red"), _btn("cmd-scrollto", "scrollToContent"), ] ), dmc.Text("Tools", size="sm", fw=600, c="dimmed"), dmc.Group( [ _btn("cmd-tool-rect", "setActiveTool: rectangle"), _btn("cmd-tool-arrow", "setActiveTool: arrow"), _btn("cmd-tool-select", "setActiveTool: selection"), ] ), dmc.Text("UI", size="sm", fw=600, c="dimmed"), dmc.Group( [ _btn("cmd-toast", "setToast"), _btn("cmd-sidebar", "toggleSidebar"), ] ), ], ), ), canvas_frame( DashExcalidraw( id="commands-canvas", height="600px", ) ), ], ) def _cmd(type_: str, payload: dict | None = None) -> dict: return {"id": f"{type_}-{uuid.uuid4()}", "type": type_, "payload": payload or {}} @callback( Output("commands-canvas", "command"), Input("cmd-update", "n_clicks"), Input("cmd-reset", "n_clicks"), Input("cmd-scrollto", "n_clicks"), Input("cmd-tool-rect", "n_clicks"), Input("cmd-tool-arrow", "n_clicks"), Input("cmd-tool-select", "n_clicks"), Input("cmd-toast", "n_clicks"), Input("cmd-sidebar", "n_clicks"), prevent_initial_call=True, ) def _dispatch(update_, reset_, scrollto_, rect_, arrow_, sel_, toast_, sidebar_): trigger = dash.ctx.triggered_id if trigger == "cmd-update": return _cmd( "updateScene", { "elements": [ { "id": f"seeded-{int(time.time())}", "type": "ellipse", "x": 200, "y": 200, "width": 300, "height": 180, "angle": 0, "strokeColor": "#e67700", "backgroundColor": "#fff4e6", "fillStyle": "solid", "strokeWidth": 2, "roughness": 1, "opacity": 100, "seed": 42, "version": 1, "versionNonce": 42, "isDeleted": False, "groupIds": [], "frameId": None, "boundElements": [], "updated": 1, "link": None, "locked": False, } ] }, ) if trigger == "cmd-reset": return _cmd("resetScene") if trigger == "cmd-scrollto": return _cmd("scrollToContent", {"opts": {"fitToViewport": True}}) if trigger == "cmd-tool-rect": return _cmd("setActiveTool", {"type": "rectangle"}) if trigger == "cmd-tool-arrow": return _cmd("setActiveTool", {"type": "arrow"}) if trigger == "cmd-tool-select": return _cmd("setActiveTool", {"type": "selection"}) if trigger == "cmd-toast": return _cmd( "setToast", {"message": "Toast dispatched from Python!", "duration": 2500}, ) if trigger == "cmd-sidebar": # "default" is the sidebar; "library" is a tab within it. Naming # the tab as the sidebar is a silent no-op — see docs/library. return _cmd("toggleSidebar", {"name": "default", "tab": "library"}) return no_update ``` :defaultExpanded: false :withExpandedButton: true --- *Source: /commands* --- # Coverage > The three commands and ten props no other example reaches — the leftovers of the prop surface, in one runnable place. --- ### Why this page exists Every other page here demonstrates a feature. This one covers the leftovers. The component ships 38 props and 12 command types. Sweeping every example module for the commands it dispatches — both the `{"type": "X"}` dict form and the `_cmd("X", …)` helper form — and for every prop reached either as a constructor keyword or through an `Input`/`Output`/`State`, three commands and ten props came back untouched. A reader could find them in the component reference and nowhere else. That is the gap this page closes. It is not a tutorial; it is the part of the surface that would otherwise be documented only as a table row. ### The three commands | `type` | What it does here | How you see it | |:-------|:------------------|:---------------| | `addFiles` | Registers one 1×1 PNG as raw `BinaryFileData` | The readout's *registered file ids* grows | | `exportToCanvas` | Exports the scene through a canvas element | The preview appears, tagged with the dispatched `id` | | `updateLibrary` | Merges a two-rectangle item into the library | The library panel opens with the item in it | `addFiles` registers **bytes**, not a visible element. Excalidraw draws an image only when a scene element references the file id, so the file appearing in the readout while the canvas stays empty is correct, not a failure — see [File uploads](/file-uploads) for the flow that pairs the two. `exportToCanvas` returns a `data:` URL, where `exportToSvg` returns markup. Both land on `lastExport` carrying the id you dispatched, which is what lets you tell two in-flight exports apart. [Export round-trip](/export) covers the correlation. ### The ten props | Prop | Default | What it does | Live? | |:-----|:--------|:-------------|:------| | `langCode` | `"en"` | Excalidraw's UI language | Yes | | `name` | *(unset)* | Scene name, used by the export dialog | Yes | | `width` | `"100%"` | CSS width of the container | Yes | | `detectScroll` | `True` | Canvas handles wheel events | Yes | | `handleKeyboardGlobally` | `True` | Key handling on `document`, not the canvas | Yes | | `hideExcalidrawLinks` | `True` | Hides the vendor's links group | Yes | | `docsLinkUrl` | `"https://excalidraw.2plot.dev"` | Our own menu item's URL; `""` renders none | Yes | | `docsLinkLabel` | `"dash-excalidraw docs"` | That item's visible label | Yes | | `autoFocus` | `True` | Focus the canvas on mount | Mount only | | `libraryReturnUrl` | *(unset)* | Where the Browse Library trip returns to | Mount only, in effect | | `appState` | — | Full serializable app state | Read-only | | `sceneVersion` | — | Monotonic scene counter | Read-only | `autoFocus` is read by Excalidraw when the canvas mounts. A switch for it would be theatre — this page sets it to `False` and that takes effect on page load, nowhere else. Reload to change it. `appState` and `sceneVersion` are written *out* by the component. Setting them from Python does nothing; the readout on the right is what they are for. `sceneVersion` is a single integer and far cheaper to compare than diffing `elements`, which is the reason it exists. ### The main menu is composed here, not by Excalidraw The wrapper renders its own `MainMenu` rather than letting Excalidraw render the default one. It mirrors the vendor's `DefaultMainMenu` item for item and in the same order — Load scene, Save to file, Export, Save as image, Find, Help, Reset canvas, then the links, then Theme and Canvas background. It does that because there is no other supported way to control the links group: the vendor's `Socials` item is composed at a single site inside Excalidraw and no `UIOptions` key reaches it. Two consequences worth knowing: - **Each canvas decides for itself.** `hideExcalidrawLinks` is a render condition on this canvas's own menu, so it works in both directions and two canvases on one page can disagree. It was one-way until R5 — a shared stylesheet that went in and never came out — and this page said so. - **Two switches are ours to keep in step.** Most default items decide their own visibility, but `Export` and `Save as image` are gated by Excalidraw where the menu is composed. Composing our own means replicating exactly those two, so `UIOptions.canvasActions.export` and `.saveAsImage` still work. A test in the JS harness reads the vendor's own composition and fails if a version bump changes the item set, rather than letting our copy quietly become a copy of an older menu. | State | Vendor links group | Our docs item | |:------|:-------------------|:--------------| | Default | hidden | shown | | `hideExcalidrawLinks=False` | shown | shown | | `docsLinkUrl=""` | hidden | none | `docsLinkLabel` exists so that re-pointing the URL does not leave a menu entry naming one destination and opening another. If you send `docsLinkUrl` to your own site, relabel it. ### What still points at Excalidraw Being honest about the residue: the menu is not the only place the vendor links out, and the rest is deliberately left alone. - **The Help dialog** links to `docs.excalidraw.com`, `plus.excalidraw.com/blog`, the Excalidraw GitHub issues tracker and their YouTube channel. - **Two error dialogs** link to the vendor's FAQ and to "open an issue". That is Excalidraw's manual for Excalidraw's canvas, and a wrapper that rewrote it would be sending people to the wrong project for help with the thing that is actually failing. Out of scope on purpose. ### Live demo ### Source ```python # File: docs/coverage/coverage.py """Coverage: the three commands and ten props no other example page reaches. Measured, not guessed — an AST sweep of every `docs/*/*.py` for command types (both the `{"type": "X"}` dict literal and the `_cmd("X", ...)` helper form) and for props reached via a constructor kwarg or an Input/Output/State dependency. What was left over is what this page exists to exercise. """ import time import uuid import dash_mantine_components as dmc from dash import Input, Output, State, callback, html, no_update from dash_excalidraw import DashExcalidraw from docs._shared import canvas_frame, code_block, json_panel, sync_canvas_theme, two_column sync_canvas_theme("coverage-canvas") # A real 1x1 PNG. Small enough to read inline, valid enough that Excalidraw # accepts it as BinaryFileData rather than silently dropping the entry. PNG_1PX = ( "data:image/png;base64," "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8" "z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==" ) CODE = """ # The three commands no other page dispatches. # addFiles — RAW BinaryFileData list. You supply `created` and `mimeType`; # an entry missing either is ignored, so a bad payload is a silent no-op. {'id': cmd_id, 'type': 'addFiles', 'payload': [{'id': file_id, 'mimeType': 'image/png', 'dataURL': PNG_1PX, 'created': int(time.time() * 1000)}]} # exportToCanvas — async; the result arrives on `lastExport`, carrying the # id you dispatched. A data: URL, not an SVG string. {'id': cmd_id, 'type': 'exportToCanvas', 'payload': {'mimeType': 'image/png'}} # updateLibrary — merge items into the user's library. {'id': cmd_id, 'type': 'updateLibrary', 'payload': {'libraryItems': [item], 'merge': True, 'openLibraryMenu': True}} """ def _rect(x: int, y: int, colour: str, bg: str) -> dict: now = int(time.time()) return { "id": f"cov-{uuid.uuid4()}", "type": "rectangle", "x": x, "y": y, "width": 120, "height": 80, "angle": 0, "strokeColor": colour, "backgroundColor": bg, "fillStyle": "solid", "strokeWidth": 2, "roughness": 1, "opacity": 100, "seed": now % 100000, "version": 1, "versionNonce": now % 100000, "isDeleted": False, "groupIds": [], "frameId": None, "boundElements": [], "updated": 1, "link": None, "locked": False, } def _btn(btn_id: str, label: str, colour: str) -> dmc.Button: return dmc.Button(label, id=btn_id, color=colour, size="sm", variant="light") LANGS = ["en", "fr-FR", "de-DE", "zh-CN", "es-ES"] controls = dmc.Paper( withBorder=True, p="md", radius="md", children=dmc.Stack( gap="sm", children=[ dmc.Text("Props no other page sets", size="sm", fw=600, c="dimmed"), dmc.SimpleGrid( cols={"base": 1, "sm": 2, "md": 3}, spacing="sm", children=[ dmc.Select( id="cov-lang", label="langCode", description="Excalidraw UI language", data=LANGS, value="en", size="xs", ), dmc.Select( id="cov-name", label="name", description="Scene name in the export dialog", data=["coverage-scene", "renamed-scene"], value="coverage-scene", size="xs", ), dmc.Select( id="cov-width", label="width", description="CSS width of the container", data=["100%", "75%", "50%"], value="100%", size="xs", ), dmc.Switch( id="cov-detectscroll", label="detectScroll", description="Canvas handles wheel events", checked=True, size="sm", ), dmc.Switch( id="cov-keyboard", label="handleKeyboardGlobally", description="Key handling on document, not canvas", checked=True, size="sm", ), dmc.Switch( id="cov-hidelinks", label="hideExcalidrawLinks", description="Hides the GitHub/Discord/X menu group", checked=True, size="sm", ), ], ), ], ), ) component = dmc.Stack( gap="md", children=[ dmc.Alert( color="blue", variant="light", title="What this page is for", children=( "Every other example page demonstrates a feature. This one " "exists to cover the leftovers: the three command types and " "ten props that no other page reaches. If a prop is listed " "in the component reference but you cannot find it exercised " "anywhere, it is here." ), ), code_block(CODE), dmc.Group( gap="sm", children=[ _btn("cov-addfiles", "addFiles", "grape"), _btn("cov-exportcanvas", "exportToCanvas", "teal"), _btn("cov-updatelibrary", "updateLibrary", "indigo"), ], ), controls, two_column( canvas_frame( DashExcalidraw( id="coverage-canvas", height="520px", width="100%", name="coverage-scene", langCode="en", detectScroll=True, handleKeyboardGlobally=True, hideExcalidrawLinks=True, # autoFocus is read by Excalidraw at MOUNT only, so a # switch for it would be theatre — it is set here and # takes effect on page load, nowhere else. autoFocus=False, # Only observable by taking the Browse Library round trip; # it is where that trip returns to. libraryReturnUrl="https://excalidraw.2plot.dev/coverage", ) ), dmc.Stack( gap="sm", children=[ html.Div(id="cov-readout"), html.Div(id="cov-export-out"), ], ), ), ], ) @callback( Output("coverage-canvas", "langCode"), Output("coverage-canvas", "name"), Output("coverage-canvas", "width"), Output("coverage-canvas", "detectScroll"), Output("coverage-canvas", "handleKeyboardGlobally"), Output("coverage-canvas", "hideExcalidrawLinks"), Input("cov-lang", "value"), Input("cov-name", "value"), Input("cov-width", "value"), Input("cov-detectscroll", "checked"), Input("cov-keyboard", "checked"), Input("cov-hidelinks", "checked"), ) def _drive_props(lang, name, width, detect, keyboard, hidelinks): return lang, name, width, bool(detect), bool(keyboard), bool(hidelinks) @callback( Output("coverage-canvas", "command"), Input("cov-addfiles", "n_clicks"), Input("cov-exportcanvas", "n_clicks"), Input("cov-updatelibrary", "n_clicks"), prevent_initial_call=True, ) def _dispatch(_add, _export, _library): import dash trigger = dash.ctx.triggered_id cmd_id = str(uuid.uuid4()) if trigger == "cov-addfiles": return { "id": cmd_id, "type": "addFiles", "payload": [ { "id": f"cov-file-{cmd_id[:8]}", "mimeType": "image/png", "dataURL": PNG_1PX, "created": int(time.time() * 1000), } ], } if trigger == "cov-exportcanvas": return { "id": cmd_id, "type": "exportToCanvas", "payload": {"mimeType": "image/png"}, } if trigger == "cov-updatelibrary": return { "id": cmd_id, "type": "updateLibrary", "payload": { "libraryItems": [ { "id": f"cov-lib-{cmd_id[:8]}", "status": "unpublished", "created": int(time.time() * 1000), "elements": [ _rect(100, 100, "#5f3dc4", "#d0bfff"), _rect(240, 100, "#0b7285", "#99e9f2"), ], } ], "merge": True, "openLibraryMenu": True, }, } return no_update # Three INPUTS, not one input and two states, and the distinction is the whole # reason this panel looked dead. `sceneVersion` tracks ELEMENTS: registering a # file does not change it, and neither does panning or zooming. So with it as # the only Input, clicking addFiles updated nothing — the command had worked # and the panel simply never re-ran — and appState's zoom and scroll could # never appear at all, because a State is only read when some Input fires. @callback( Output("cov-readout", "children"), Input("coverage-canvas", "sceneVersion"), Input("coverage-canvas", "files"), Input("coverage-canvas", "appState"), ) def _readout(scene_version, files, app_state): state = app_state or {} return json_panel( "sceneVersion + appState (both read-only)", { "sceneVersion": scene_version, "registered file ids": sorted((files or {}).keys()), "appState.zoom": (state.get("zoom") or {}).get("value"), "appState.scrollX": state.get("scrollX"), "appState.scrollY": state.get("scrollY"), "appState.viewBackgroundColor": state.get("viewBackgroundColor"), "appState.activeTool": (state.get("activeTool") or {}).get("type"), # The `name` prop lands here. Without this row the page offered a # control for `name` and no way to observe it — its only other # surface is the export dialog's filename, which you have to open # a modal to see. A demo you cannot watch is indistinguishable # from one that does not work. "appState.name (the `name` prop)": state.get("name"), }, height=200, ) @callback( Output("cov-export-out", "children"), Input("coverage-canvas", "lastExport"), prevent_initial_call=True, ) def _show_export(export): if not export: return no_update if export.get("error"): return dmc.Alert( f"{export['type']} (id {export['id']}) failed: {export['error']}", color="red", variant="light", ) result = export.get("result") or "" return dmc.Stack( gap="xs", children=[ dmc.Text( f"lastExport carries id {export.get('id')} for {export.get('type')}", size="sm", fw=600, ), dmc.Image(src=result, h=120, fit="contain") if result.startswith("data:image") else dmc.Code(result[:200], block=True), ], ) ``` :defaultExpanded: false :withExpandedButton: true --- *Source: /coverage* --- # Events > Every Excalidraw callback surfaced as a timestamped snapshot prop you can read from a Dash callback. --- ### Overview Every Excalidraw callback is surfaced as a setProps-written snapshot prop on the Python side. Interact with the canvas and watch the panels update. ### Live demo ### Source ```python # File: docs/events/events.py """Events: observe pointer/scroll/paste/library snapshots.""" import dash_mantine_components as dmc from dash import Input, Output, callback from dash_excalidraw import DashExcalidraw from docs._shared import ( canvas_frame, code_block, json_panel, sync_canvas_theme, two_column, ) sync_canvas_theme("events-canvas") CODE = """ @callback( Output('pointer-out', 'children'), Input('canvas', 'lastPointerMove'), ) def show_pointer(snapshot): return json.dumps(snapshot) if snapshot else '(waiting)' """ component = dmc.Stack( gap="md", children=[ code_block(CODE), two_column( canvas_frame( DashExcalidraw( id="events-canvas", height="560px", pointerMoveThrottleMs=75, scrollThrottleMs=150, ), min_height=560, ), dmc.Stack( gap="sm", children=[ dmc.Tabs( value="pointer", children=[ dmc.TabsList( [ dmc.TabsTab("Pointer", value="pointer"), dmc.TabsTab("Scroll", value="scroll"), dmc.TabsTab("Paste", value="paste"), dmc.TabsTab("Links", value="links"), ] ), dmc.TabsPanel( value="pointer", pt="sm", children=dmc.Stack( gap="xs", children=[ dmc.Text( "lastPointerDown / Up / Move", size="sm", fw=600, ), dmc.Paper(id="events-pointer", withBorder=True, p="xs"), ], ), ), dmc.TabsPanel( value="scroll", pt="sm", children=dmc.Paper(id="events-scroll", withBorder=True, p="xs"), ), dmc.TabsPanel( value="paste", pt="sm", children=dmc.Paper(id="events-paste", withBorder=True, p="xs"), ), dmc.TabsPanel( value="links", pt="sm", children=dmc.Paper(id="events-link", withBorder=True, p="xs"), ), ], ), ], ), ), ], ) @callback( Output("events-pointer", "children"), Input("events-canvas", "lastPointerDown"), Input("events-canvas", "lastPointerUp"), Input("events-canvas", "lastPointerMove"), ) def _render_pointer(down, up, move): return dmc.Stack( gap="xs", children=[ json_panel("lastPointerDown", down, height=120), json_panel("lastPointerUp", up, height=120), json_panel("lastPointerMove", move, height=120), ], ) @callback( Output("events-scroll", "children"), Input("events-canvas", "lastScrollChange"), ) def _render_scroll(scroll): return json_panel("lastScrollChange", scroll, height=220) @callback( Output("events-paste", "children"), Input("events-canvas", "lastPaste"), ) def _render_paste(paste): return json_panel("lastPaste", paste, height=220) @callback( Output("events-link", "children"), Input("events-canvas", "lastLinkOpen"), ) def _render_link(link): return json_panel("lastLinkOpen", link, height=220) ``` :defaultExpanded: false :withExpandedButton: true --- *Source: /events* --- # Export round-trip > Export to SVG, PNG blob or canvas through an async command/lastExport round-trip correlated by id. --- ### Overview Excalidraw's export utilities are async. The wrapper models the round-trip as (1) Python writes `command`, (2) JS awaits the export and writes `lastExport` with the same id, (3) Python reads the result. ### Live demo ### Source ```python # File: docs/export/export.py """Export: drive exportToSvg / exportToBlob / exportToCanvas via command.""" import uuid import dash import dash_mantine_components as dmc from dash import Input, Output, State, callback, html, no_update from dash_excalidraw import DashExcalidraw from docs._shared import ( canvas_frame, code_block, sync_canvas_theme, two_column, ) sync_canvas_theme("export-canvas") CODE = """ # Python -> component: dispatch an export command return {'id': str(uuid.uuid4()), 'type': 'exportToSvg', 'payload': {'exportPadding': 20}} # component -> Python: observe lastExport and match ids @callback(Output('preview', 'children'), Input('canvas', 'lastExport')) def preview(result): if result and result['type'] == 'exportToSvg': return html.Iframe(srcDoc=result['result']) """ component = dmc.Stack( gap="md", children=[ code_block(CODE), two_column( canvas_frame( DashExcalidraw( id="export-canvas", height="520px", initialData={ "elements": [ { "id": "s1", "type": "rectangle", "x": 150, "y": 150, "width": 220, "height": 140, "angle": 0, "strokeColor": "#2f9e44", "backgroundColor": "#d3f9d8", "fillStyle": "solid", "strokeWidth": 2, "roughness": 1, "opacity": 100, "seed": 7, "version": 1, "versionNonce": 7, "isDeleted": False, "groupIds": [], "frameId": None, "boundElements": [], "updated": 1, "link": None, "locked": False, } ], "scrollToContent": True, }, ), min_height=520, ), dmc.Stack( gap="sm", children=[ dmc.Paper( withBorder=True, p="md", radius="md", children=dmc.Stack( gap="sm", children=[ dmc.Text("Dispatch", size="sm", fw=600, c="dimmed"), dmc.Group( [ dmc.Button( "Export SVG", id="export-svg-btn", variant="light", ), dmc.Button( "Export PNG", id="export-png-btn", variant="light", color="teal", ), ] ), ], ), ), dmc.Paper( withBorder=True, p="md", radius="md", children=dmc.Stack( gap="sm", children=[ dmc.Text("Preview", size="sm", fw=600, c="dimmed"), dmc.Box(id="export-preview", style={"minHeight": 180}), ], ), ), ], ), ), ], ) @callback( Output("export-canvas", "command"), Input("export-svg-btn", "n_clicks"), Input("export-png-btn", "n_clicks"), prevent_initial_call=True, ) def _dispatch_export(_svg, _png): trigger = dash.ctx.triggered_id if trigger == "export-svg-btn": return { "id": f"svg-{uuid.uuid4()}", "type": "exportToSvg", "payload": {"exportPadding": 20}, } if trigger == "export-png-btn": return { "id": f"png-{uuid.uuid4()}", "type": "exportToBlob", "payload": {"mimeType": "image/png", "exportPadding": 20}, } return no_update @callback( Output("export-preview", "children"), Input("export-canvas", "lastExport"), ) def _render_preview(result): if not result or "result" not in result: return dmc.Text("(dispatch an export to preview)", c="dimmed", size="sm") export_type = result.get("type") payload = result.get("result") if not payload: err = result.get("error") or "empty result" return dmc.Alert(color="red", variant="light", children=str(err)) if export_type == "exportToSvg": return html.Iframe( srcDoc=payload, style={ "width": "100%", "height": "260px", "border": "0", "background": "white", }, ) if export_type in ("exportToBlob", "exportToCanvas"): return html.Img( src=payload, style={"maxWidth": "100%", "maxHeight": "260px", "display": "block"}, ) return dmc.Text(f"Unhandled export type: {export_type}", c="dimmed") ``` :defaultExpanded: false :withExpandedButton: true --- *Source: /export* --- # File uploads > Keep canvas JSON small: push pasted images to external storage and swap the base64 for URLs. --- ### Where the bytes go, and how to point that at a CDN A dropped file arrives as **base64** — that is how the browser hands it over, and it is the wrong place for it to stay. Inline in the scene, a 120 KB image is ~160 KB of base64 inside every `serializedData` you persist, every callback payload that carries the scene, and every undo step. The job of this page is getting it out. The path is four steps, and only the third is deployment-specific: 1. **The canvas emits the bytes.** `lastFileAdded` for an image Excalidraw placed; `lastExternalDrop` for anything else — including GIFs, for the reason below. Both carry a `dataURL`. 2. **Python decodes and stores it.** `decode_data_url` → the storage backend's `put(key, mime, data)`, which returns a **URL**. 3. **The bytes live wherever the backend puts them.** In-process by default. 4. **The canvas is pointed at the URL.** `replaceFiles` for images; for other files the placeholder gets a `link`, and a GIF's placeholder is replaced by an `embeddable` whose iframe loads the stored file. Either way `externalizedSerializedData` comes back with every `data:` URI stripped — that is the payload you persist. #### The storage backend is a seam `lib/file_backends.py` defines it, and it is three methods: ```python class FileBackend: def put(self, key, mime_type, data) -> str: ... # store; return a URL def get(self, key) -> tuple[str, bytes] | None: ... # None if this app # does not serve them def url_for(self, key) -> str: ... ``` `EXCALIDRAW_FILE_BACKEND` chooses one: `memory` (default) or `disk` (`EXCALIDRAW_FILE_DIR`). An unknown name **raises at boot** rather than falling back — a store that is silently not the one you configured is worse than a failure to start. For Cloudflare R2, S3 or a Postgres blob table, implement those three and register it: ```python from lib.file_backends import FileBackend, register_backend class R2Backend(FileBackend): name = "r2" def put(self, key, mime_type, data): bucket.put_object(Key=key, Body=data, ContentType=mime_type) return self.url_for(key) def get(self, key): return None # the CDN serves them; this app never does def url_for(self, key): return f"https://cdn.example.com/{key}" register_backend("r2", R2Backend) ``` Nothing above storage changes. The canvas only ever needed a URL back. **Two things change once the URL is not this app's origin**, and both are the deployment's to solve rather than the component's. **CORS**: Excalidraw fetches image bytes, so the bucket must allow your site's origin — a CDN that serves `` happily can still refuse a cross-origin fetch. And **lifetime**: the default backend's caps exist because it holds bytes in a web process on a 512 MB container; a bucket has none of those constraints and should not inherit limits sized for somebody else's. #### Why GIFs take a different route Excalidraw **rasterises a dropped GIF to a single still frame** before anything downstream sees it. Measured here: a 123,069-byte GIF89a of 12 frames arrives as a 2,820-byte PNG with none. So uploading what the canvas hands you stores a still, and framing that in an iframe frames a still — the animation was lost at the drop, not at the embed. The rasterisation is also what freezes the tab on a large one. Dropping a 5.17 MB 600×600×20 GIF left the renderer unable to answer a debugger evaluation at all — two 45-second timeouts — while the server sat idle at 32 callbacks and logged no error. It is decode work on the main thread, not I/O, and no storage change touches it. (Timer-based "scheduling lag" is **not** a usable measure here: a backgrounded tab is throttled to ~1 s, so an idle page with no GIF reports the same figure as a wedged one. An earlier draft of this note quoted those numbers before that was checked against a control.) So the component intercepts a GIF drop and sends the **original bytes** down the `lastExternalDrop` path, exactly like a `.pdf` or a `.txt`. Excalidraw never decodes it. This page then stores those bytes and puts an `embeddable` where the placeholder was, so the browser animates the real file. The trade is that a GIF is an embed rather than an image element: it is not croppable or styleable on the canvas, and it needs the storage URL to be reachable from the browser. That is the price of it moving at all. #### An embed always draws above the canvas, whatever the z-order says **Bring to front will not lift a shape above a GIF**, and that is not a bug in this page — it is how Excalidraw renders. Measured in the DOM: | layer | what is in it | z-index | |---|---|---| | `.excalidraw__canvas.static` | every rectangle, image, arrow and text — painted as pixels into **one** bitmap | 1 | | `.excalidraw__embeddable-container` | every embed, as real `