@emblemvault/hustle-react 1.1.1 → 1.2.0

package/dist/browser/hustle-react.js

@@ -3621,6 +3621,21 @@ var buildPluginTool = {
   name: "build_plugin",
   description: `Build a Hustle plugin definition. Use this tool to construct a plugin based on user requirements.
 
+## Testing Before Building (IMPORTANT)
+
+If the execute_javascript tool is available, use it to prototype and test code BEFORE building the plugin. This allows rapid iteration without the overhead of building/installing/uninstalling.
+
+**Workflow:**
+1. When a user describes what they want, first test the core logic using execute_javascript
+2. Iterate on the code until it works correctly
+3. Ask the user: "Would you like to test this further, or should I build it into a plugin?"
+4. Only call build_plugin once the code is validated and the user confirms
+
+**Example:** If building a weather plugin, first test the API call:
+execute_javascript({ code: "fetch('https://api.example.com/weather?city=London').then(r => r.json()).then(console.log)" })
+
+This catches errors early and lets users see results before committing to a plugin.
+
 ## Plugin Structure
 
 A plugin consists of:
@@ -3737,11 +3752,49 @@ Hooks also have full access to the browser scope described above.
 2. **Namespace console logs** with [PluginName] prefix for easy identification
 3. **Handle errors gracefully** in executors - return { error: message } instead of throwing
 
+## Building Plugin UI
+
+Plugins can embed custom UI elements in two ways:
+
+### Persistent UI (via onRegister hook)
+Use the onRegister hook to embed UI that persists across the chat session. Check if your element already exists to avoid duplicates on re-registration:
+
+"async () => {
+  console.log('[MyPlugin] v1.0.0 registered');
+  if (document.getElementById('my-plugin-panel')) return; // Already exists
+
+  const panel = document.createElement('div');
+  panel.id = 'my-plugin-panel';
+  Object.assign(panel.style, { position: 'fixed', bottom: '20px', right: '20px', padding: '10px', background: '#333', color: '#fff' });
+  panel.textContent = 'My Panel';
+  document.body.appendChild(panel);
+}"
+
+### On-Demand UI (via tool executors)
+Embed UI just-in-time when a tool is invoked. Useful for tools like show_clock, display_chart, etc.:
+
+"async (args) => {
+  const modal = document.createElement('div');
+  modal.id = 'clock-modal';
+  Object.assign(modal.style, { position: 'fixed', inset: '0', display: 'flex', alignItems: 'center', justifyContent: 'center', background: 'rgba(0,0,0,0.5)' });
+  modal.textContent = 'Current time: ' + new Date().toLocaleTimeString();
+  modal.onclick = () => modal.remove(); // Click to dismiss
+  document.body.appendChild(modal);
+  return { success: true, message: 'Clock displayed' };
+}"
+
+### UI Best Practices
+- Always use unique IDs with your plugin name prefix (e.g., "myplugin-modal")
+- For persistent UI, check existence in onRegister before creating
+- Provide a way to dismiss/close UI elements (click handler, close button)
+- Use Object.assign(el.style, {...}) for inline styles or inject a <style> tag
+- Clean up UI in tool executors if appropriate (e.g., remove after timeout)
+
 ## Security Notes
 - Code runs in browser sandbox with same-origin policy
 - fetch() is subject to CORS restrictions
 - No direct filesystem access (use File API with user interaction)
-- Be careful with eval() on user input`,
+- Sanitize any user-provided content before inserting into the DOM`,
   parameters: {
     type: "object",
     properties: {