API Documentation

create(type, params)

Create a new item on the canvas.

// Create text
const text = app.create('text', {
  content: 'Hello!',
  x: 400,
  y: 300,
  fontSize: 64,
  color: '#3730a3'
});

// Create circle
const circle = app.create('circle', {
  x: 200,
  y: 200,
  radius: 50,
  color: '#ef4444'
});

select(query, replace)

Select items on the canvas.

// Select an item
app.select(item);

// Select all items
app.select('all');

// Select by type
app.select({ type: 'text' });

modify(changes)

Modify selected items.

app.modify({
  fontSize: 72,
  color: '#10b981',
  rotation: 45
});

animate(item, params)

Apply animation to an item.

app.animate(item, {
  animationType: 'pulse',
  animationSpeed: 1.5,
  animationDelay: 0.5
});

removeSelectedItems()

Remove all currently selected items from the canvas.

app.select('all');
app.removeSelectedItems();

nudgeSelection(dx, dy)

Move selected items by pixel offset.

// Move right 10px, down 5px
app.nudgeSelection(10, 5);

Timeline UI Components

The timeline interface provides visual control over animation timing:

• ▸ Playhead - Red vertical line showing current time position
• ▸ Tracks - Horizontal rows for each animatable item
• ▸ Keyframes - Diamond markers indicating animation points
• ▸ Interpolation Curves - Visual representation of easing between keyframes
• ▸ Transport Controls - Play, pause, stop, and loop buttons

window.timelineUI

Global timeline controller object.

// Access timeline
const timeline = window.timelineUI;

// Set 5 second duration
timeline.setDuration(5);

// Play the animation
timeline.play();

// Seek to 2.5 seconds
timeline.seek(2.5);

// Pause playback
timeline.pause();

addKeyframe(item, time, properties, easing)

Add a keyframe to an item at a specific time.

// Fade in animation
timelineUI.addKeyframe(text, 0, { opacity: 0 }, 'linear');
timelineUI.addKeyframe(text, 2, { opacity: 1 }, 'easeOut');

// Move and scale animation
timelineUI.addKeyframe(shape, 0, { x: 100, scaleX: 0.5, scaleY: 0.5 }, 'linear');
timelineUI.addKeyframe(shape, 1.5, { x: 400, scaleX: 1, scaleY: 1 }, 'easeInOut');

applyPreset(item, presetName)

Apply a predefined animation preset to an item.

// Apply fade in preset
timelineUI.applyPreset(text, 'fadeIn');

// Apply pop in effect
timelineUI.applyPreset(title, 'popIn');

// Apply continuous pulse
timelineUI.applyPreset(logo, 'pulse');

Easing Functions

Control how values interpolate between keyframes.

setBackgroundMode(mode)

Switch between background modes.

// Activate drawing mode
app.setBackgroundMode('drawing');

Basic Path Drawing

Create paths programmatically using Paper.js:

// Basic freehand-style path
const path = new Path();
path.strokeColor = '#FF0000';
path.strokeWidth = 5;
path.strokeCap = 'round';
path.strokeJoin = 'round';

// Add points to create the path
path.add(new Point(100, 100));
path.add(new Point(150, 120));
path.add(new Point(200, 100));
path.add(new Point(250, 130));

// Smooth the path for organic look
path.smooth();

Brush Style Properties

Paper.js path properties for different brush effects:

Brush Style Examples

// Dotted/Stipple brush
const dottedPath = new Path();
dottedPath.strokeColor = 'blue';
dottedPath.strokeWidth = 2;
dottedPath.dashArray = [2, 8]; // dot pattern

// Marker/Highlighter style (semi-transparent overlay)
const markerPath = new Path();
markerPath.strokeColor = new Color(1, 1, 0, 0.5); // Yellow with alpha
markerPath.strokeWidth = 20;
markerPath.strokeCap = 'round';
markerPath.blendMode = 'multiply';

// Neon glow effect
const neonPath = new Path();
neonPath.strokeColor = '#00ff00';
neonPath.strokeWidth = 3;
neonPath.shadowColor = '#00ff00';
neonPath.shadowBlur = 10;

// Spray/Airbrush effect (multiple small circles)
function sprayBrush(center, radius, density, color) {
  for (let i = 0; i < density; i++) {
    const offset = new Point({
      angle: Math.random() * 360,
      length: Math.random() * radius
    });
    const dot = new Path.Circle({
      center: center.add(offset),
      radius: Math.random() * 2 + 0.5,
      fillColor: color
    });
    dot.opacity = Math.random() * 0.5 + 0.2;
  }
}

// Usage: sprayBrush(new Point(200, 200), 30, 50, '#ff6b6b');

Drawing Configuration

Get and set drawing settings:

// Get current settings
const color = app.getDrawColor();
const width = app.getDrawWidth();
const mode = app.getBackgroundMode();

// Modify settings
app.setDrawColor('#3b82f6');
app.setDrawWidth(8);

clearDrawings()

Clear all freehand drawings from the canvas.

app.clearDrawings();

executeGenerator(name, params)

Execute a background generator function with custom parameters.

// Stacked circles with Poisson disk sampling
app.executeGenerator('drawStackedCircles', {
  colors: ['#4f46e5', '#7c3aed', '#2563eb', '#0891b2'],
  count: 50,
  distribution: 'poisson',  // 'poisson', 'golden', 'random'
  minRadius: 20,
  maxRadius: 100,
  bgColor: '#1a1a2e'
});

// Circuit board pattern
app.executeGenerator('drawCircuit', {
  lineColor: '#22c55e',
  bgColor: '#0a0a0a',
  nodeSize: 6,
  gridSize: 60,
  animated: true
});

// Grid pattern
app.executeGenerator('drawGrid', {
  gridType: 'dots',  // 'lines', 'dots', 'squares'
  spacing: 40,
  lineColor: '#374151',
  bgColor: '#1f2937'
});

Distribution Utilities New

Low-level utilities for procedural placement of elements.

// Generate Poisson disk points for natural placement
const points = app.poissonDiskSampling(800, 600, 50);

// Place shapes at each point with noise-based variation
points.forEach(p => {
  const noise = app.simpleNoise(p.x, p.y, 100);
  const radius = 10 + noise * 40;
  const color = app.getColorFromPosition(['#ff0', '#0ff', '#f0f'], p.x, p.y);

  new Path.Circle({
    center: [p.x, p.y],
    radius: radius,
    fillColor: color,
    parent: app.patternGroup
  });
});

getAvailableGenerators()

Get list of all available background generators with their parameter schemas.

const generators = app.getAvailableGenerators();
// Returns array of:
// {
//   name: 'drawStackedCircles',
//   displayName: 'Stacked Circles',
//   description: 'Overlapping circles with glow',
//   params: {
//     colors: { type: 'colors', default: [...], description: '...' },
//     count: { type: 'number', min: 10, max: 100, default: 30 },
//     distribution: { type: 'select', options: ['poisson', 'golden', 'random'] }
//   }
// }

setBackgroundColor(color)

Set solid background color.

app.setBackgroundColor('#0B0F19');

arrowSystem.createArrow(points, config)

Create an arrow programmatically with full configuration.

// Create arrow with full config
app.arrowSystem.createArrow(
  [new Point(100, 100), new Point(200, 150), new Point(300, 100)],
  {
    lineColor: '#60a5fa',
    lineWidth: 3,
    style: 'smooth',
    smoothness: 60,
    headStyle: 'stealth',  // 'classic', 'stealth', 'open', 'none'
    headSize: 1.2,
    boltEnabled: true,
    boltColor: '#fbbf24'
  }
);

Arrowhead Styles

arrowSystem.updateArrowSettings(config)

Update settings for selected arrow or set defaults for new arrows.

// Update arrow settings
app.arrowSystem.updateArrowSettings({
  headStyle: 'stealth',
  lineWidth: 5,
  lineColor: '#ef4444'
});

Arrow Management

// Get all arrows
const arrows = app.arrowSystem.arrows;

// Clear all arrows
app.arrowSystem.clear();

// Remove specific arrow
app.arrowSystem.removeArrow(arrow);

applyEffect(item, effectType, config)

Apply particle effects to any item (text, shapes, arrows).

Sparkle Config:

app.applyEffect(item, 'sparkle', {
  color: '#fbbf24',  // Particle/glow color
  speed: 1.0,        // Animation speed multiplier
  size: 3            // Bolt size
});

Blast Config:

app.applyEffect(item, 'blast', {
  color: '#ef4444',  // Particle color
  radius: 100,       // Blast radius/speed
  count: 20          // Number of particles
});

effectSystem.removeEffectsFrom(item)

Remove all effects from an item.

// Remove effects from specific item
app.effectSystem.removeEffectsFrom(item);

// Clear ALL effects
app.effectSystem.clear();

Effect Lifecycle

Effects are automatically managed:

• • Sparkle effects persist and are saved with templates
• • Blast effects are transient (one-shot, not saved)
• • Effects are stored in item.data.effects array
• • Call effectSystem.rebuildEffects() after loading scenes

getSceneState()

Get a semantic description of the current scene for AI agents.

const state = app.getSceneState();
// Returns: { canvas, items, arrows, background }

exportTemplate()

Export current scene as a template (full state capture).

const template = app.exportTemplate();
// Save template JSON for later restoration

loadScene(templateData)

Load a complete scene from template data.

app.loadScene(templateData);

clearCanvas()

Clear all items and reset the canvas.

app.clearCanvas();

Zoom Methods

• zoomIn() - Zoom in by 20%
• zoomOut() - Zoom out by 20%
• resetZoom() - Reset to 1:1 zoom

app.zoomIn();
app.zoomOut();
app.resetZoom();

PinePaper is built on Paper.js, a powerful vector graphics scripting framework. All Paper.js globals are available in the editor scope.

Key Paper.js Objects

// Create shapes directly
const circle = new Path.Circle({
  center: [200, 200],
  radius: 50,
  fillColor: '#3b82f6'
});

// Create text
const text = new PointText({
  point: [100, 100],
  content: 'Hello',
  fillColor: 'black',
  fontSize: 24
});

// Access view
view.center; // Canvas center point
view.size;   // Canvas size
view.zoom;   // Current zoom level

// Access project
project.activeLayer; // Current active layer
project.exportSVG(); // Export as SVG

// Listen to PinePaper events
window.addEventListener('selectionChanged', (e) => {
  console.log('Selected:', e.detail.items);
});

window.addEventListener('modeChanged', (e) => {
  console.log('Mode:', e.detail.mode);
});

Overview

The Item Registry tracks all canvas items with unique IDs, types, and declarative associations. Every item (text, shape, generator element) is automatically registered.

Querying Items

// Get all registered items
const allItems = app.itemRegistry.getAll();

// Get items by type
const textItems = app.itemRegistry.getByType('text');
const circles = app.itemRegistry.getByType('circle');

// Get items by source
const userItems = app.itemRegistry.getBySource('user');
const generatorItems = app.itemRegistry.getBySource('generator');

// Get item by ID
const item = app.itemRegistry.getItem('item_5');

// Check if item exists
if (app.itemRegistry.has('item_5')) { /* ... */ }

// Get item count
const count = app.itemRegistry.count();

// Custom query with predicate
const largeItems = app.itemRegistry.query(entry =>
  entry.item.bounds.width > 100
);

Item Associations

Create relationships between items for complex scene logic:

// Create relationships
app.itemRegistry.addAssociation('item_1', 'item_2', 'orbits');
app.itemRegistry.addAssociation('item_1', 'item_3', 'contains');

// Query associations
const orbiting = app.itemRegistry.getAssociations('item_1', 'orbits');
const allRelated = app.itemRegistry.getAssociations('item_1');

// Remove association
app.itemRegistry.removeAssociation('item_1', 'item_2', 'orbits');

Item Properties & Names

// Update item properties
app.itemRegistry.updateProperties('item_1', {
  customProp: 'value',
  animationType: 'pulse'
});

// Set item name for identification
app.itemRegistry.setName('item_1', 'MainTitle');

// Find by name
const headers = app.itemRegistry.getByName('MainTitle');

Built-in Relations

addRelation(fromId, toId, relation, params)

Create a behavior-driven relationship between two items.

// Make moon orbit earth
app.addRelation(moonId, earthId, 'orbits', {
  radius: 100,
  speed: 0.5,
  direction: 'counterclockwise'
});

// Make label follow player
app.addRelation(labelId, playerId, 'follows', {
  offset: [0, -50],  // 50px above
  smoothing: 0.1
});

// Attach name tag to character
app.addRelation(nameTagId, characterId, 'attached_to', {
  offset: [0, -30]
});

Querying Relations

// Get all relations for an item
const relations = app.getRelations(itemId);

// Get specific relation type
const orbits = app.getRelations(itemId, 'orbits');

// Find items that orbit a specific target
const orbiters = app.queryByRelationTarget(earthId, 'orbits');

// Check if relation exists
if (app.hasRelation(moonId, earthId, 'orbits')) {
  console.log('Moon orbits Earth');
}

// Remove a relation
app.removeRelation(moonId, earthId, 'orbits');

Advanced Queries

Powerful query methods for complex scene analysis:

// Compound query with multiple conditions
const results = app.queryCompound([
  { relation: 'orbits' },              // Must orbit something
  { relation: 'follows', not: true }   // Must NOT follow anything
]);

// Chain query - follow relation chains
const chains = app.queryRelationChain(['follows', 'orbits']);

// Find items with no relations
const isolated = app.queryIsolatedItems();

// Get relation statistics
const stats = app.getRelationStats();
// { activeItems: 5, ruleCount: 8, associationsByType: {...} }

Overview

Web Worker pool for offloading heavy computations. Keeps the UI responsive during complex operations. Includes automatic fallback to main thread if Workers are unavailable.

Available Operations

// Poisson disk sampling (non-blocking)
const points = await app.workerPool.poissonDiskSampling(800, 600, 50);

// Golden ratio distribution
const spiralPoints = await app.workerPool.goldenRatioDistribution(100, 800, 600);

// Path simplification (Douglas-Peucker algorithm)
const simplified = await app.workerPool.simplifyPath(points, 5);

// Color calculations for large datasets
const colors = await app.workerPool.calculateColors(positions, palette, 0.01);

// Scene serialization (for large scenes)
const json = await app.workerPool.serializeScene(sceneData);
const scene = await app.workerPool.deserializeScene(jsonString);

Worker Status & Statistics

// Check if workers are available
if (app.workerPool.isAvailable()) {
  // Use async methods
}

// Get performance statistics
const stats = app.workerPool.getStats();
// { tasksCompleted, tasksFailed, averageTaskTime, workersActive, ... }

// Warm up workers (pre-initialize)
await app.workerPool.warmUp();

Using Async Generators

Async generators leverage Web Workers for computation-heavy operations, keeping the UI responsive.

// Execute async generator (non-blocking)
await app.generatorRegistry.executeAsync('drawPoissonShapesAsync', {
  shape: 'circle',
  minDistance: 40,
  colors: ['#8B5CF6', '#A78BFA']
});

Creating Custom Async Generators

app.generatorRegistry.register('myAsyncGenerator', {
  displayName: 'My Async Pattern',
  description: 'Pattern using Web Workers',
  category: 'custom',
  async: true,  // Mark as async
  params: {
    count: { type: 'number', default: 100 }
  },
  fn: async function(ctx) {
    const { params, register, patternGroup, view } = ctx;

    // Use async helpers from WorkerPool
    let points;
    if (ctx.async && ctx.async.poissonDiskSampling) {
      // Non-blocking computation via Web Worker
      points = await ctx.async.poissonDiskSampling(
        view.size.width, view.size.height, 30, 30
      );
    }

    // Create visuals on main thread
    const group = new Group({ parent: patternGroup });
    points.forEach(pt => {
      new Path.Circle({
        center: [pt.x, pt.y],
        radius: 5,
        fillColor: '#8B5CF6',
        parent: group
      });
    });

    register(group, 'myPattern', { count: points.length });
  }
});

Async Context Helpers:

• ctx.async.poissonDiskSampling(w, h, dist, attempts) - Poisson sampling
• ctx.async.goldenRatioDistribution(count, w, h, padding) - Golden spiral
• ctx.async.simplifyPath(points, tolerance) - Path simplification
• ctx.async.calculateGeneratorPositions(config) - Generic position calc

Overview

Register custom animation callbacks with built-in performance guardrails. Callbacks are automatically monitored and can be disabled if they impact performance.

// Add a callback (called every frame)
app.addOnFrameCallback('myAnimation', (event) => {
  // event.delta - time since last frame
  // event.time - total elapsed time
  // event.count - frame count
  myItem.rotate(event.delta * 30); // 30 degrees per second
}, {
  throttleMs: 16,  // Optional: minimum ms between calls
  priority: 0      // Optional: execution order
});

// Remove callback
app.removeOnFrameCallback('myAnimation');

// Remove all callbacks
app.clearOnFrameCallbacks();

Features:

• Built-in performance monitoring
• Automatic throttling for slow callbacks
• Priority-based execution order

Animation Optimization

// Get count of animated items
const count = app.getAnimatedItemCount();

// Stop all animations on an item
app.stopAnimation(item);

// Rebuild animation tracking (after scene load)
app.rebuildAnimatedItemsSet();