Docs

Debugging

Canvas apps run in a WebView, and like any web application, you need proper debugging tools to inspect elements, view console logs, and diagnose issues. This guide covers how to enable and use developer tools for Canvas app development.

Enabling Developer Tools

Canvas apps have Safari Web Inspector support built-in. When properly configured, you can:

  • Inspect DOM elements
  • View console logs
  • Debug JavaScript
  • Monitor network requests
  • Profile performance

Prerequisites

  1. macOS 13.3 or later - Required for full WebView inspection support
  2. Safari Developer Menu enabled - Must be enabled in Safari preferences

Enable Safari Develop Menu

If you haven't already enabled Safari's Develop menu:

  1. Open Safari
  2. Go to Safari > Settings (or press Cmd+,)
  3. Click the Advanced tab
  4. Check "Show features for web developers" (or "Show Develop menu in menu bar")

Enable Safari Develop Menu

Inspecting Canvas Apps

Once developer tools are enabled, you can inspect any Canvas app:

Method 1: Right-Click Context Menu

  1. Open a Canvas app in the Agentastic launcher
  2. Right-click anywhere on the Canvas content
  3. Select "Inspect Element" from the context menu

Right-click Inspect Element

Method 2: Safari Develop Menu

  1. Open a Canvas app in the Agentastic launcher
  2. Open Safari
  3. Go to Develop menu in the menu bar
  4. Find your Mac's name in the submenu
  5. Select the agentastic-launcher WebView

Safari Develop Menu

Web Inspector Features

Safari's Web Inspector provides comprehensive debugging tools:

Elements Panel

Inspect and modify the DOM in real-time:

  • View HTML structure
  • Edit element attributes
  • Modify inline styles
  • Find elements by selector

Elements Panel

Console Panel

View logs and execute JavaScript:

// Your app's console.log() calls appear here
console.log('App initialized');

// Execute code in the context of your app
Agentastic.llm.ask({ user: 'Hello' }).then(console.log);

Common console outputs:

  • Bridge connection status
  • LLM request/response logs
  • Error messages and stack traces
  • Custom debug logs from your app

Console Panel

Network Panel

Monitor all network activity:

  • API calls to Agentastic services
  • Asset loading (images, scripts, styles)
  • Request/response headers and bodies
  • Timing information

Network Panel

Sources Panel

Debug JavaScript with breakpoints:

  1. Find your script in the Sources tree
  2. Click line numbers to set breakpoints
  3. Use the debugger controls (pause, step, continue)
  4. Inspect variables in the scope panel

Sources Panel

Debugging Common Issues

"Not authenticated" Error

If you see "Error: Not authenticated. Please sign in." in your Canvas app:

  1. Open the Console panel in Web Inspector
  2. Look for authentication-related errors
  3. Verify you're signed into Agentastic
  4. Check that your app has the required permissions in manifest.yaml
# Ensure your manifest includes necessary permissions
permissions:
  - llm
  - net:fetch

Bridge Connection Issues

If Agentastic object is undefined:

  1. Ensure the bridge script is loaded: 
    <script src="agentastic://sdk/bridge.js"></script>
  2. Wait for the bridge to be ready: 
    document.addEventListener('agentastic:ready', () => {
  // Bridge is now available
  console.log('Bridge ready:', Agentastic);
});

LLM Request Failures

Debug LLM issues by wrapping calls in try-catch:

try {
  const response = await Agentastic.llm.ask({
    user: 'Hello',
    model: 'gpt-4.1-mini'
  });
  console.log('Response:', response);
} catch (error) {
  console.error('LLM Error:', error);
  console.error('Error details:', error.message);
}

Console Logging Best Practices

Add structured logging to your Canvas apps:

// Use different log levels
console.log('Info: App loaded');
console.warn('Warning: Using fallback model');
console.error('Error: Failed to fetch data');

// Log objects for inspection
console.log('State:', { user: 'John', theme: 'dark' });

// Group related logs
console.group('LLM Request');
console.log('Prompt:', prompt);
console.log('Model:', model);
console.log('Response:', response);
console.groupEnd();

// Time operations
console.time('llm-request');
const result = await Agentastic.llm.ask({ user: prompt });
console.timeEnd('llm-request'); // Outputs: llm-request: 1234ms

Testing Workflows

Development Cycle

  1. Make changes to your Canvas app code
  2. Reload the app - Right-click and select "Reload" in the Canvas
  3. Check console for errors
  4. Inspect elements to verify UI changes
  5. Test functionality and monitor network

Testing Checklist

  • App loads without console errors
  • All UI elements render correctly
  • LLM requests complete successfully
  • Error states are handled gracefully
  • Permissions are properly declared
  • Works in both light and dark themes

Performance Profiling

Use the Timelines panel to profile your app:

  1. Open Web Inspector
  2. Go to the Timelines tab
  3. Click the record button
  4. Interact with your app
  5. Stop recording and analyze:
    • JavaScript execution time
    • Layout/paint operations
    • Memory usage

Performance Timeline

Troubleshooting Web Inspector

"Inspect Element" Not Appearing

If right-click only shows "Reload":

  1. Verify you're running macOS 13.3+
  2. Check that Safari's Develop menu is enabled
  3. Ensure the app was built with debugging enabled
  4. Try restarting the Agentastic launcher

WebView Not Appearing in Safari Develop Menu

  1. Close and reopen Safari
  2. Restart the Agentastic launcher
  3. Open a Canvas app
  4. Check Develop menu again

Inspection Works But Console Is Empty

  1. Add explicit console.log statements to your code
  2. Check that your script is actually being loaded
  3. Look for JavaScript errors that might be blocking execution
  4. Verify the bridge script is loaded before your app code

Tips for Effective Debugging

  1. Start with the Console - Most issues show up as errors or warnings
  2. Use breakpoints - Pause execution at key points
  3. Check Network tab - Verify API calls are being made
  4. Inspect the DOM - Ensure elements are rendering as expected
  5. Profile performance - Find bottlenecks in complex apps
  6. Test authentication - Many issues stem from auth problems

Next Steps