Choose a visual that helps answer the user's question: relationships for an
architecture, steps for a process, aligned views for a comparison, or linked
inputs and results for a simulation. Every control should visibly change the
diagram, selection, result, or explanation. Do not substitute a long statistics
report for a relationship diagram or add decorative controls with no effect.
Read Shared visual guidance through skill_view
before creating a visual. Then read the relevant modules, combining them when
useful; they describe general capabilities, not a fixed catalog of examples:
relationships and hierarchies.
proportions and correlations.
custom data graphics and maps from available embedded data.
calculators and controls that visibly change the result.
prototypes with local demonstration interactions.
choices or constraints needed for an explicitly requested subsequent task.
For example, a selectable architecture uses diagrams plus interactive guidance;
a filterable dataset uses charts or data views plus interactive guidance. Choose
the visual from the user's question, not from the examples below. A plain answer,
Markdown table or static diagram may already be sufficient.
These generated references preserve the MIT-licensed generative-frame 0.0.5
guidance with explicit OpenSquilla host adaptations. Source hashes, adaptation
records and license text are bundled in upstream-guidance.json andLICENSE.generative-frame.txt. The publication and host contracts in this file
and the three optional examples below are OpenSquilla content.
Default to a compact HTML fragment with its own styles and scripts and callshow_widget(title="short_title", widget_code="...") to place it directly in
the conversation. Full HTML documents and workspace files remain supported for
existing canvases or tasks that need them. The host supplies the isolated frame
and its controls; fragments do not need html, head, body, or a second page
shell. Use open_workspace_preview only when the user asks for an editable
source file, a downloadable webpage, a multi-file bundle, or a workbench page.
Let the surrounding answer introduce and explain the visual. Use a small local
title only when it helps. Avoid repeating the answer's title inside a large hero,
adding app navigation, or nesting many bordered cards. Prefer one clear visual
and nearby controls; reveal secondary detail on selection. A simulation may
need more space than a diagram: optimize for understanding, not a fixed layout.
Use fluid widths, wrapping controls, touch-friendly targets, readable labels and
keyboard access. Use the available container width and reflow when resized or
expanded. Check that the result also works at 360 px; this is a narrow-screen
acceptance width, not a fixed canvas width or a request for a phone mockup. Only
use a phone-sized device frame when the user explicitly requests a phone-screen
prototype. Keep main text and controls at the host's normal size, at least 14 px;
use 16 px input text and reserve 12 px for secondary captions. For full documents
include a viewport meta tag. Keep the background transparent unless a meaningful region
needs contrast. Use the full host token table and native-control styles in the
shared guidance; do not invent a separate palette or oversized primary buttons.
The host handles frame spacing, expansion, reload and export controls.
Optional original OpenSquilla examples show design choices, not a component
catalog or required templates. Read only the relevant example via skill_view:
units, state restoration, and a concrete result check.
nodes and edges, selectable detail, and a small-screen alternative.
views, a step control, and observable differences.
For a pure in-chat visual, call show_widget with the exact HTML fragment or
standalone SVG. It returns an internal immutable Visualize Artifact receipt for
conversation recovery and remote clients; it is not a user-facing Files entry.
Place its returned marker between the relevant explanatory paragraphs using
the system prompt's inline visual delivery format. For example:
visualize:doc_example:rev_example
Use only the marker returned by the tool; do not invent IDs. The tool does not
finish the response. Continue explaining what the user can try and what it means.
For a targeted update, call edit_widget with exact old_string → new_string
replacements copied from the latest widget code. Each old string must occur
exactly once; include enough neighboring text to make it unique. This advances
the same widget's immutable Artifact revision and keeps its conversation
identity. Use show_widget again under the same title only for a broad rewrite
or when the widget does not exist yet.
When a file or bundle is required, create the self-contained file in the current
workspace, then callopen_workspace_preview(path="relative/path.html", presentation="inline").
Use the exact marker from that result as above. This path remains the supported
one for source delivery and multi-file resources.
For several file-backed examples, give each a separate file and include each final
marker beside its explanation. For inline widgets, use a distinct title and the
returned marker for each example; no workspace file is needed.
The host Canvas menu owns explicit exports such as Download HTML and Download
PNG. Do not create a workspace HTML file merely to make a visual downloadable;
the user can request an export from the inline Canvas when needed.
inline-ready means the bytes were registered, not that a browser rendered them.renderStatus: not-observed is not a successful visual check. Before publishing,
check key calculations with named input/output cases and check all control
handlers. When browser tools are available, inspect the published version in
the actual host at desktop and narrow widths, operate its controls, and check
state restoration and follow-up behavior. Distinguish what you tested from what
you could not observe. Never infer successful interaction from registration.
If publication returns a correctable HTML input error, fix that specific problem
and publish again; do not blindly repeat the same bytes. If a user supplies a
canvas error, use its revision and diagnosis to repair the source, then publish
a new version. A retry does not verify the new version's behavior by itself.
The canvas is an isolated browser document running on desktop, remote WebUI and
mobile browsers. Bundle all CSS, JavaScript, SVG, and data in the HTML. Do not use
network fetches, CDNs, local file paths, external frames, cookies or localStorage.
Use SVG/Canvas/native DOM for charts and diagrams. Keep the file under 1 MiB.
The host provides window.opensquillaVisualize before your scripts execute:
const visual = window.opensquillaVisualize;
await visual.ready;
const saved = visual.getState(); // a small JSON value, or null/undefined
// Validate saved values into your local state before the first render.Restore all important inputs, selections, tabs and simulation progress from
saved state on startup, validate their ranges, and derive outputs from that
state. Await readiness and capture getState() before the first render or anysetState() call. A render function that also saves must not run with defaults
before restoration: that would overwrite the saved state before you read it.
Keep render/resize functions free of state writes. Callvisual.setState(currentState) from validated change/reset handlers after
restoration. Keep initialization separate from saving user changes. Verify a
non-default selection survives both canvas reload and a session round trip.
For paused simulations, preserve the visible time, angle or progress as well as
the pause flag: restoring the controls while resetting the picture is not a
successful restore. Save these on discrete user changes or pause, not every
animation frame. Treat zero as a valid value and accept older snapshots with
missing fields.
Save after changes and after reset; saving only the selected tab is not
enough when the user has adjusted parameters. Keep serialized state under 16,384
JavaScript string code units. State belongs to the current browser session,
account, conversation and stable widget identity; edits to that widget can restore
the saved state. Validate older saved values when changing the state schema.
State does not synchronize across devices and is not durable shared storage.
Calculations, filtering, selection, highlighting, playback and ordinary prototype
actions stay local. Do not add a generic "continue discussion" or submit-to-chat
button to complete a visual. New visuals must not call legacy sendPrompt.
The local visual should answer the question without an extra model turn.
Use this only when the requested workflow benefits from model work with the
user's chosen conditions. Ordinary charts and simulations do not need it. The
host provides a consistent action to use prepared conditions in the conversation;
do not recreate that action inside the generated HTML.
// After valid task conditions change, including restored conditions:
await visual.setContext({
summary: "A selected route with a 20-minute transfer limit",
data: { selectedRoute: "route-a", maxTransferMinutes: 20 },
suggestedPrompt: "Compare this route with alternatives under these conditions."
});
// Clear a stale or invalid selection:
await visual.setContext(null);summary is required, nonempty text up to 400 characters. Optional data is
plain JSON with finite numbers, nesting depth at most eight from its root, and
at most 2048 JSON nodes. OptionalsuggestedPrompt is task-specific editable text up to 2000 characters. The whole
context must fit in 8 KiB of JSON; no other fields, functions, cycles or secrets.
Describe actual selected values, units and the requested next task, not generic
"continue" text. Do not copy the whole document into context.
setContext acknowledges preparation only: it does not call the model, send a
message, change the chat draft, or make state automatically visible to the model.
The user chooses the host action to add a removable conditions block and an
editable draft, then sends the message from the chat composer. Preserve this
distinction in any feedback. Keep fields editable; update or clear context when
conditions change or become invalid. Recompute useful context after restoring
local state rather than assuming an old context snapshot is still active.
Never request tool execution or credentials from inside the canvas.