pub(super) const DASHBOARD_WIDGET_COMPLETION_CONTRACT: &str = "Dashboard widget completion contract: complete the first created widget to the user's requested outcome before giving the final answer. All AI Created Widgets are script widgets. If the request implies live/realtime data, MCP-backed data, web-fetched data, local file/session data, or any other changing external input, do not create a text-only placeholder or scaffold. In the same assistant turn, use multiple tool-call rounds as needed to discover schemas, read or fetch sample data, inspect real responses, self-correct validation errors, and then create a script widget wired to the actual data source with loading, error, empty, and refresh states. Use polling or event refresh when freshness matters. For static requests, create a small script widget that renders concise DOM inside #root using KKTerm's built-in classes. If missing credentials or API access blocks live data, create settingsSchema secret/config fields and request the secret after creation, or ask one narrow blocking question instead of shipping a fake widget.";
pub(super) const DASHBOARD_WIDGET_ARCHETYPE_CONTRACT: &str = "Dashboard Widget Archetype contract: before authoring source, choose exactly one widgetArchetype for dashboard_create_widget. dataMonitor is for web/API/list/status data and must include compact provenance plus loading, error, empty, stale, refresh, and freshness states when data can change. metricChart is for numeric summaries, gauges, charts, meters, timelines, and local performance counters; ambient is allowed when the widget renders a compact in-body title because a bare number can be ambiguous. utilityInstrument is for QR, hash, converter, calculator, parser, generator, formatter, encoder/decoder, and similar arbitrary tools; default to panel, explicit labels, validation, result areas, and copy/export affordances. desktopObject is for clocks, dials, notes, trays, scanners, calculators, tuners, and tactile singleton objects; default to ambient, hide host title chrome, and avoid body subtitles or explanatory prose. canvasToyGame is for small games, physics toys, fidget tools, and canvas/SVG/WebGL scenes; default to ambient, hide host title chrome, and put score, status, pause/reset, and controls inside the scene as HUD affordances. generalWorkbench is a last-resort fallback for mixed-purpose widgets only when none of the five primary archetypes fits; default to panel with one primary work region. The selected archetype must drive preset, source structure, lifecycle, library choice, and grid size.";
pub(super) const DASHBOARD_WIDGET_VISUAL_CONTRACT: &str = "Dashboard widget visual contract: active Dashboard page context includes activeView.visualContext with colorScheme, backgroundKind, backgroundTone, backgroundId, and requiresOpaqueTextSurface. Keep this as the coarse prompt payload; exact runtime colors are available inside script widgets through KK.getTheme() and CSS variables --kk-text, --kk-muted, --kk-surface, --kk-surface-muted, --kk-readable-surface, --kk-readable-surface-text, --kk-border, --kk-accent, and --kk-accent-soft. Use those tokens instead of inventing a color system. If requiresOpaqueTextSurface is true, put all text-bearing UI on kk-panel, kk-card, kk-result, or another opaque surface using --kk-readable-surface; do not place translucent text directly over image, video, dynamic, or mixed backgrounds.";
pub(super) const DASHBOARD_WIDGET_DESIGN_DIRECTION_CONTRACT: &str = "OpenDesign-style design direction contract: before authoring an AI Created Widget, choose one internal visual direction from this bounded library and make every visual decision serve it. Operator console: dense technical surface, terminal-adjacent contrast, grids, meters, log-like rhythm, and restrained signal colors. Data observatory: charts, gauges, timelines, maps, and numeric hierarchy that make the data feel alive without marketing chrome. Desktop object: a single tactile object such as a clock, dial, calculator, tray, note, tuner, scanner, or instrument with focused controls. Spatial canvas: canvas/WebGL/SVG-first visual widgets such as 3D scenes, physics toys, diagrams, weather, maps, or animated monitors where the visual field is the product. Branded vignette: image-led or editorial widgets for user-supplied brands, references, places, or media, using one strong asset plus restrained UI. If the user provides a brand/reference/screenshot, extract its palette, typography posture, density, and motion cues instead of asking for a separate direction. If no direction is specified, pick the strongest fit silently; ask one narrow style question only when two directions would create meaningfully different widgets.";
pub(super) const DASHBOARD_WIDGET_DESIGN_PREFLIGHT_CONTRACT: &str = "Widget design preflight: before calling dashboard_create_widget, silently write a tiny design brief for yourself: selected Widget Archetype, selected direction, primary visual metaphor, data hierarchy, chosen library or native DOM/canvas approach, preset/accent/icon/grid size, empty/loading/error states, and motion budget. Then run a self-critique against contrast, hierarchy, density, responsiveness, and motion cost. Revise the planned source before the first tool call if the critique finds low contrast, too much prose, an inner scrollbar, generic form layout, unbounded animation, mismatched library choice, or a widget that does not look like a finished singleton object.";
pub(super) const DASHBOARD_WIDGET_SURFACE_CONTRACT: &str = "Dashboard widget surface contract: treat the widget root as the full allocated surface. Script widgets should make their outermost wrapper fill 100% width and height, usually with kk-shell, kk-stage, kk-panel, or kk-fill, and use KK.getViewport() plus KK.onViewportResize for canvases and visual libraries. Do not create a smaller centered app card, duplicate the host widget frame, or leave accidental blank space around the main content. If the useful object is naturally smaller, still use a full-size wrapper to align, center, or scale it intentionally. Script widgets should avoid max-width, fixed-height, or shrink-to-content outer wrappers unless the user explicitly asks for an inset miniature object.";
pub(super) const DASHBOARD_WIDGET_ANIMATION_CONTRACT: &str = "Dashboard widget animation contract: declare body.lifecycle.kind explicitly. Use 'animation' for widgets that should always be visibly moving (spinners, clocks, orbits, meters, ambient 3D); the host runs a stall watchdog and reports the widget as 'stalled' to the assistant if no rAF callbacks fire for 8 seconds while the widget is visible. Use body.lifecycle.minTickMs: 16 for intentional smooth canvas/WebGL animation that should target 60 fps; the host honors minTickMs with a 16 ms lower bound. Use 'periodic' for widgets that refresh on an interval (counters, polled data). Use 'realtime' for widgets driven by external events (websockets, MCP streams). Use 'static' (the default when lifecycle is null) for non-moving content. For 'animation' widgets, design a durable base motion that does not decay to a static frame: drag/flick velocity may decay, but auto-spin or live animation needs an idle speed, fresh time-based angle, or restart path. If a requestAnimationFrame loop pauses while KK.isVisible() is false, use KK.onVisibilityChange((visible) => { if (visible) restartAnimation(); }) to restart that loop when visibility returns instead of leaving the widget frozen.";
pub(super) const DASHBOARD_WIDGET_PHYSICS_CONTRACT: &str = "Dashboard widget physics contract: for 2D physics, prefer the bundled Matter.js library instead of hand-rolling collision, gravity, constraints, or rigid-body integration. List body.libraries [\"matter\"] and call the Matter global from source. Size the Matter renderer/canvas from KK.getViewport(), rebuild or reposition static wall/floor bodies on KK.onViewportResize, keep the simulation bounded to the widget arena, and stop Runner or requestAnimationFrame work when the widget is paused, game-over, capped, or no longer needs animation.";
pub(super) const DASHBOARD_WIDGET_PERFORMANCE_COUNTER_CONTRACT: &str = "Dashboard performance counter contract: for local performance widgets, use a script widget that calls await KK.getPerformanceCounters(). It returns a low-overhead local snapshot with CPU, RAM, commit, process/thread/handle counts, aggregate network rates, KKTerm process memory/I/O rates, uptime, and system-drive free space. Poll at a modest interval such as 2-5 seconds; do not use requestAnimationFrame for counters.";
pub(super) const DASHBOARD_WIDGET_UTF8_CONTRACT: &str = "Dashboard widget UTF-8 contract: preserve every non-English title, summary, label, placeholder, setting option, HTML shim, and script string exactly as Unicode text. Treat widget body JSON, bodyJson, settingsSchemaJson, and generated JavaScript as UTF-8 text end to end. Do not convert UI text through Latin-1, Windows-1252, percent encoding, base64, escaped mojibake, HTML entities, or ASCII-only transliteration unless the user explicitly asks for that representation.";
pub(super) const DASHBOARD_WIDGET_DOM_CONTRACT: &str = "Dashboard widget DOM contract: the generated source is smoke-checked before it is saved. Build the UI from the provided #root element with document.createElement and root.replaceChildren, or provide htmlShim for every extra element id you query. Do not call document.getElementById('some-id').innerHTML/textContent/appendChild unless that id is root, appears in htmlShim, or is created in source before use. After a dashboard_create_widget or dashboard_update_custom_widget call, inspect the tool result; if validation reports a DOM mount, JSON, library, or script-source error, fix the widget and retry before yielding to the user.";
