list_visualizations
Read-only
List the workspace’s visualization library — the workspace-shared entries plus your own, archived ones excluded. CALL THIS BEFORE create_visualization: each row carries the author’s description of what the entry draws and what row shape it expects, so reusing or improving an existing entry is usually right and authoring a near-duplicate is usually not. Rows also report how many dashboards bind the entry and its last render error, if any. You supply the workspace; pass mine:true for only your own entries, includeArchived:true to also list archived entries (archived manually, or automatically after 90 days bound to no active dashboard).
get_visualization
Read-only
Return one library visualization in full — its metadata, its complete code, and its recent sealed versions (rev + when, for restore_visualization_version). Use before editing an entry, to pattern-match a new visualization against a working one, or to investigate a render error: the code is the contract, the description is only a summary. You supply the workspace and entry id. Any workspace member may read any entry by id — visibility governs listings and new bindings, not reads.
create_visualization
Additive write
Create a visualization library entry: user-authored code that draws a chart the built-in renderers can’t (chord, beeswarm, ridgeline, hexbin, waterfall, Gantt). Use only when neither a Vistazo-native kind nor an ECharts option can express the chart, and only after list_visualizations shows nothing reusable — authoring code costs materially more than emitting a config. You supply a name, a REQUIRED description (what it draws and what row shape it expects), and code: an ES module whose default export takes { data, width, height, theme, container } and draws SVG into container. The frame has no network and no imports — data arrives only from the widget’s pipeline, and D3 (core + sankey/hexbin/cloud/geo) and topojson are already frame globals. The function is called again on every resize, so it must redraw itself; colours come from theme slots, never literals. Nothing is validated at save: mistakes surface as render errors on the widget. Supply sampleRows (small placeholder rows matching the declared shape) so the Library page can preview the entry — without them it has no preview. Entries are private to you until you set visibility ‘workspace’. Bind the entry to a dashboard with add_widget type visualizationRef, then ask the user to confirm it renders as designed — you cannot see the output.
update_visualization
Destructive write
Update a library visualization: its code, description, name, engine label, visibility, archived state, or sampleRows (small placeholder rows that power the Library page’s preview — add them to entries that lack one; keep them matching the row shape whenever the code changes shape). LIVE REFERENCE — an entry has one head and every dashboard bound to it renders that head immediately, so a code edit changes every bound widget the moment it lands. Check the entry’s boundDashboardCount first (list_visualizations / get_visualization) and tell the user what else will change before editing a shared entry. Use this to fix or improve an existing entry rather than creating a near-duplicate. archived:true retires the entry from listings (refused while any dashboard still binds it); archived:false restores it, and a code edit restores it implicitly. Code and description edits seal a version after a quiet period; name, engine label, visibility, and archived are metadata and never seal one. The author or a workspace admin may edit.
restore_visualization_version
Destructive write
Roll a library visualization’s code and description back to a recorded version (rev from get_visualization). Use when an edit broke the entry and an earlier version was known good. The current code is sealed as a version first, so a restore is reversible. This writes the entry HEAD, so every dashboard bound to it renders the restored code immediately — rolling library code back is deliberately an act on the entry, where that blast radius is visible, rather than on one widget. Author or workspace admin.
delete_visualization
Destructive write
Delete a library visualization permanently. REFUSES while any non-archived dashboard still binds it, naming those dashboards — repoint or remove those widgets first, so deleting can never blank a rendering dashboard. Use for genuine cleanup of an unbound or archived entry; there is no undo and no restore. Confirm with the user only when their request does NOT identify the entry unambiguously (“delete the old map” in a library holding three maps); when the request names the visualization, or you resolved the id from list_visualizations and it matches what was asked for, that request IS the confirmation — verify the id, then delete it. Author or workspace admin.
list_gallery_visualizations
Read-only
List the starter gallery: Vistazo-authored, contract-conforming visualizations covering what ECharts genuinely lacks (waterfall, beeswarm, Gantt, and whatever ships next). Each row carries the slug, name, and a description of the data shape it expects. Check the gallery BEFORE authoring a chart of one of these shapes from scratch — forking a working implementation is cheaper and better than writing one.
fork_gallery_visualization
Additive write
Copy a starter-gallery visualization into this workspace as a library entry you own (the fork IS the delivery model — no live link back, so a Vistazo update can never change your dashboards underneath you). Use when the gallery shape matches the need, then bind it with add_widget type visualizationRef and edit the fork freely with update_visualization. You supply the gallery slug; optional name and visibility (default private) as for create_visualization.