Agent Mode

Agent Mode provides a streamlined workflow for AI agents (Claude, ChatGPT, Gemini, etc.) accessing PinePaper through MCP or direct API calls.

Overview

Agent Mode optimizes PinePaper for programmatic access by:

• Skipping user onboarding UI (welcome modals, help overlays)
• Enabling batch operations for reduced tool calls
• Providing deterministic, screenshot-free workflows
• Auto-detecting agent mode via URL parameters
• Smart export format recommendations based on content

Quick Start

// Agent Mode is globally available
const agent = window.PinePaperAgent;

// Configure agent mode
await agent.configure({ mode: 'agent' });

// Wait for PinePaper to be ready
await agent.waitForReady();

// Now use the PinePaper API
const text = app.create('text', { content: 'Hello', x: 400, y: 300 });

// Smart export with auto-format detection
const result = await agent.quickExport();

Activation Methods

1. URL Parameters (Auto-Detection)

Agent mode activates automatically with these URL parameters:

https://pinepaper.studio?agent=1
https://pinepaper.studio?agent=true
https://pinepaper.studio?mode=agent

2. Programmatic Configuration

await PinePaperAgent.configure({
  mode: 'agent',              // 'agent' or 'user'
  skipOnboarding: true,       // Skip onboarding highlights
  skipWelcomeModal: true,     // Skip welcome modal
  batchMode: true,            // Enable batch operations
  defaultCanvas: 'default',   // Default canvas preset
  exportFormat: 'png',        // Default export format
  verbosity: 'normal',        // 'minimal', 'normal', 'verbose'
  autoReset: false            // Reset canvas after export
});

API Reference

Configuration

configure(options)

Configure agent mode with options.

await PinePaperAgent.configure({
  mode: 'agent',
  skipOnboarding: true,
  verbosity: 'minimal'
});

Options:

isAgentMode()

Check if agent mode is active.

if (PinePaperAgent.isAgentMode()) {
  // Agent-specific logic
}

getConfig()

Get current configuration.

const config = PinePaperAgent.getConfig();
console.log(config.mode); // 'agent'

Ready State

waitForReady()

Wait for PinePaper to be fully initialized. Returns a Promise.

await PinePaperAgent.waitForReady();
// PinePaper is now ready to use

markReady()

Called internally by app.js after initialization. Not typically called by agents.

Canvas Management

reset(options)

Reset canvas for next job. Clears all content and prepares for new creation.

// Basic reset
PinePaperAgent.reset();

// Reset with canvas preset
PinePaperAgent.reset({ canvas: 'instagram-post' });

// Reset but keep undo history
PinePaperAgent.reset({ keepHistory: true });

Options:

What reset() clears:

• All items in textItemGroup
• All items in patternGroup
• All items in drawingGroup
• ItemRegistry entries
• RelationRegistry associations
• Current selection
• Undo history (unless keepHistory: true)

getPresets()

Get all available canvas presets.

const presets = PinePaperAgent.getPresets();
// { 'instagram-post': { width: 1080, height: 1080 }, ... }

Capability Detection

getCapabilities()

Detect browser/device capabilities for optimal performance decisions.

const caps = PinePaperAgent.getCapabilities();

Returns:

Example usage:

const caps = PinePaperAgent.getCapabilities();

if (caps.webCodecs) {
  // Can use MP4 export
  await agent.quickExport({ format: 'mp4' });
} else if (caps.mediaRecorder) {
  // Fall back to WebM
  await agent.quickExport({ format: 'webm' });
} else {
  // Static export only
  await agent.quickExport({ format: 'png' });
}

Export

getExportRecommendation()

Get smart export format recommendation based on current canvas content.

const rec = PinePaperAgent.getExportRecommendation();
console.log(rec.format);  // 'png', 'mp4', 'webm', etc.
console.log(rec.reason);  // Explanation of why this format

Decision logic:

getPlatformExportSettings(platform)

Get platform-specific export settings.

const settings = PinePaperAgent.getPlatformExportSettings('instagram-post');
// { format: 'mp4', width: 1080, height: 1080, fps: 30, duration: 10 }

Available Platforms:

quickExport(options)

Perform smart export with auto-format detection.

// Auto-detect best format
const result = await PinePaperAgent.quickExport();

// Platform-specific export
const result = await PinePaperAgent.quickExport({
  platform: 'instagram-post'
});

// Explicit format
const result = await PinePaperAgent.quickExport({
  format: 'webm',
  quality: 'high'
});

Options:

Supported Formats:

• png - Static image
• svg - Animated SVG (SMIL)
• mp4 - H.264 video (requires WebCodecs)
• webm - VP9 video (MediaRecorder)
• gif - Animated GIF
• pdf - Print-ready PDF

Returns:

{
  success: true,
  format: 'mp4',
  blob: Blob,        // For video/gif/pdf
  dataUrl: string,   // For png
  svg: string,       // For svg
  mimeType: 'video/mp4'
}

Batch Workflow Example

Agent mode is optimized for batch processing multiple graphics:

const agent = window.PinePaperAgent;

// Configure once
await agent.configure({
  mode: 'agent',
  autoReset: false  // Manual reset for control
});

await agent.waitForReady();

// Process multiple jobs
const jobs = [
  { text: 'Sale!', preset: 'instagram-post', platform: 'instagram-post' },
  { text: 'New!', preset: 'tiktok', platform: 'tiktok' },
  { text: 'Hot!', preset: 'twitter-post', platform: 'twitter' }
];

const results = [];

for (const job of jobs) {
  // Reset for new job with appropriate canvas
  agent.reset({ canvas: job.preset });

  // Create content
  const text = app.create('text', {
    content: job.text,
    x: app.view.center.x,
    y: app.view.center.y,
    fontSize: 72,
    color: '#ffffff'
  });

  app.animate(text, { animationType: 'pulse' });

  // Export for platform
  const result = await agent.quickExport({ platform: job.platform });
  results.push(result);
}

console.log(`Exported ${results.length} graphics`);

MCP Server Integration

When building MCP tools, use Agent Mode for initialization:

// MCP Server tool handler
async function handlePinePaperInit() {
  const agent = window.PinePaperAgent;

  // Configure for MCP usage
  await agent.configure({
    mode: 'agent',
    verbosity: 'minimal',
    skipOnboarding: true
  });

  await agent.waitForReady();

  return {
    success: true,
    capabilities: agent.getCapabilities(),
    presets: Object.keys(agent.getPresets())
  };
}

async function handlePinePaperExport(args) {
  const agent = window.PinePaperAgent;

  // Get recommendation or use specified format
  if (!args.format) {
    const rec = agent.getExportRecommendation();
    args.format = rec.format;
  }

  return await agent.quickExport(args);
}

Global Access

Agent Mode is available globally as:

window.PinePaperAgent

The main PinePaper API remains available as:

window.PinePaper  // or window.app

See Also

• AI Agents Guide - Complete PinePaper API for agents
• MCP Integration - Building MCP server tools
• Export API - Detailed export options
• Canvas Presets - Available canvas sizes