API_SPECIFICATION.md

# Thumbnail Crafter - Comprehensive API Specification

## Overview

This API provides complete programmatic control over the Thumbnail Crafter canvas, allowing AI agents to use all features just like a human user would.

## API Interface: `window.thumbnailAPI`

All methods are exposed through the global `window.thumbnailAPI` object and return structured results.

---

## 1. Canvas Management

### `getCanvasState(): Promise<CanvasState>`
Get the complete current state of the canvas.

**Returns:**
```typescript
{
  success: true,
  objects: CanvasObject[],
  selectedIds: string[],
  canvasSize: '1200x675' | 'linkedin' | 'hf',
  bgColor: 'seriousLight' | 'light' | 'dark',
  canvasDimensions: { width: number, height: number }
}
```

### `setCanvasSize(size: string): Promise<Result>`
Set canvas dimensions.

**Parameters:**
- `size`: `'1200x675'` | `'linkedin'` | `'hf'` | `'default'`

**Returns:**
```typescript
{ success: true, size: '1200x675', width: 1200, height: 675 }
```

### `setBgColor(color: string): Promise<Result>`
Set background color.

**Parameters:**
- `color`: `'seriousLight'` | `'light'` | `'dark'` | hex color (e.g., `'#f0f0f0'`)

**Returns:**
```typescript
{ success: true, color: 'seriousLight' }
```

### `clearCanvas(): Promise<Result>`
Remove all objects from the canvas.

**Returns:**
```typescript
{ success: true, message: 'Canvas cleared', objectsRemoved: 5 }
```

### `exportCanvas(format?: string): Promise<DataURL>`
Export the canvas as an image.

**Parameters:**
- `format` (optional): `'png'` | `'jpeg'` (default: `'png'`)

**Returns:**
```typescript
{
  success: true,
  dataUrl: 'data:image/png;base64,...',
  width: 1200,
  height: 675
}
```

---

## 2. Layout Management

### `listLayouts(): Promise<LayoutList>`
Get all available layouts.

**Returns:**
```typescript
{
  success: true,
  layouts: [
    {
      id: 'seriousCollab',
      name: 'Serious Collab',
      description: 'Professional collaboration with HF logo and partner logo',
      thumbnail: '/assets/layouts/sCollab_thumbnail.png'
    },
    // ... more layouts
  ]
}
```

### `loadLayout(layoutId: string, options?: LayoutOptions): Promise<Result>`
Load a pre-designed layout.

**Parameters:**
- `layoutId`: `'seriousCollab'` | `'funCollab'` | `'sandwich'` | `'academiaHub'` | `'impactTitle'`
- `options` (optional):
  - `clearExisting` (boolean): Clear canvas before loading (default: true)
  - `variant` (string): `'default'` | `'hf'` (auto-detected from canvas size if not provided)

**Returns:**
```typescript
{
  success: true,
  layout: 'seriousCollab',
  objectsAdded: 4,
  objectIds: ['id1', 'id2', 'id3', 'id4']
}
```

---

## 3. Object Management

### `addObject(objectData: ObjectData): Promise<Result>`
Add a new object to the canvas.

**Object Types & Parameters:**

#### Text Object
```typescript
{
  type: 'text',
  text: string,
  x?: number,              // default: center
  y?: number,              // default: center
  fontSize?: number,       // default: 48
  fontFamily?: string,     // 'Inter' | 'IBM Plex Mono' | 'Bison' | 'Source Sans 3'
  fill?: string,           // hex color, default: '#000000'
  bold?: boolean,          // default: false
  italic?: boolean,        // default: false
  align?: string,          // 'left' | 'center' | 'right', default: 'left'
  hasBackground?: boolean, // default: false
  backgroundColor?: string // hex color
}
```

#### Image Object
```typescript
{
  type: 'image',
  src: string,             // URL or data URI
  x?: number,              // default: center
  y?: number,              // default: center
  width?: number,          // default: auto from image
  height?: number,         // default: auto from image
  name?: string            // optional label
}
```

#### Rectangle Object
```typescript
{
  type: 'rect',
  x?: number,              // default: 100
  y?: number,              // default: 100
  width?: number,          // default: 200
  height?: number,         // default: 200
  fill?: string,           // hex color, default: '#cccccc'
  stroke?: string,         // hex color
  strokeWidth?: number     // default: 2
}
```

**Returns:**
```typescript
{
  success: true,
  objectId: 'obj-123',
  type: 'text'
}
```

### `addHuggy(huggyId: string, options?: ObjectPosition): Promise<Result>`
Add a Huggy mascot to the canvas.

**Parameters:**
- `huggyId`: ID of the Huggy (e.g., `'huggy-chef'`, `'dragon-huggy'`)
- `options` (optional): `{ x?: number, y?: number, width?: number, height?: number }`

**Returns:**
```typescript
{
  success: true,
  objectId: 'huggy-obj-123',
  huggyId: 'huggy-chef',
  huggyName: 'Huggy Chef'
}
```

### `listHuggys(options?: { category?: string, search?: string }): Promise<HuggyList>`
Get all available Huggy mascots.

**Parameters:**
- `options` (optional):
  - `category`: `'modern'` | `'outlined'` | `'all'` (default: `'all'`)
  - `search`: Filter by name/tags

**Returns:**
```typescript
{
  success: true,
  huggys: [
    {
      id: 'huggy-chef',
      name: 'Huggy Chef',
      category: 'modern',
      thumbnail: 'https://...',
      tags: ['chef', 'cooking', 'food']
    },
    // ... more huggys
  ],
  count: 44
}
```

### `updateObject(objectId: string, updates: Partial<ObjectData>): Promise<Result>`
Update an existing object's properties.

**Parameters:**
- `objectId`: ID of the object to update
- `updates`: Partial object data (only include properties to change)

**Returns:**
```typescript
{
  success: true,
  objectId: 'obj-123',
  updated: ['text', 'fontSize', 'fill']
}
```

### `deleteObject(objectId: string | string[]): Promise<Result>`
Delete one or more objects.

**Parameters:**
- `objectId`: Single ID or array of IDs

**Returns:**
```typescript
{
  success: true,
  deleted: 3,
  objectIds: ['obj-1', 'obj-2', 'obj-3']
}
```

### `getObject(objectId: string): Promise<ObjectResult>`
Get a specific object by ID.

**Returns:**
```typescript
{
  success: true,
  object: {
    id: 'obj-123',
    type: 'text',
    text: 'Hello World',
    x: 100,
    y: 200,
    // ... all properties
  }
}
```

### `listObjects(filter?: ObjectFilter): Promise<ObjectList>`
Get all objects on the canvas.

**Parameters:**
- `filter` (optional):
  - `type`: Filter by object type
  - `isFromLayout`: Filter layout objects
  - `selected`: Only selected objects

**Returns:**
```typescript
{
  success: true,
  objects: [ /* array of objects */ ],
  count: 5
}
```

---

## 4. Selection Management

### `selectObject(objectId: string | string[], options?: SelectOptions): Promise<Result>`
Select one or more objects.

**Parameters:**
- `objectId`: Single ID or array of IDs
- `options` (optional):
  - `additive` (boolean): Add to selection instead of replacing (default: false)

**Returns:**
```typescript
{
  success: true,
  selectedIds: ['obj-1', 'obj-2'],
  count: 2
}
```

### `deselectAll(): Promise<Result>`
Deselect all objects.

**Returns:**
```typescript
{ success: true, message: 'Selection cleared' }
```

### `getSelection(): Promise<SelectionResult>`
Get currently selected objects.

**Returns:**
```typescript
{
  success: true,
  selectedIds: ['obj-1', 'obj-2'],
  count: 2,
  objects: [ /* array of selected objects */ ]
}
```

---

## 5. Layer/Z-Index Management

### `bringToFront(objectId: string): Promise<Result>`
Bring object to front (highest z-index).

### `sendToBack(objectId: string): Promise<Result>`
Send object to back (lowest z-index).

### `moveForward(objectId: string): Promise<Result>`
Move object one layer up.

### `moveBackward(objectId: string): Promise<Result>`
Move object one layer down.

**All return:**
```typescript
{ success: true, objectId: 'obj-123', newZIndex: 5 }
```

---

## 6. Transform Operations

### `moveObject(objectId: string, x: number, y: number, relative?: boolean): Promise<Result>`
Move an object to a specific position.

**Parameters:**
- `objectId`: Object ID
- `x`: X coordinate
- `y`: Y coordinate
- `relative` (optional): If true, adds to current position instead of absolute (default: false)

**Returns:**
```typescript
{ success: true, objectId: 'obj-123', x: 100, y: 200 }
```

### `resizeObject(objectId: string, width: number, height: number): Promise<Result>`
Resize an object.

**Returns:**
```typescript
{ success: true, objectId: 'obj-123', width: 300, height: 200 }
```

### `rotateObject(objectId: string, rotation: number, relative?: boolean): Promise<Result>`
Rotate an object.

**Parameters:**
- `rotation`: Rotation angle in degrees
- `relative` (optional): Add to current rotation (default: false)

**Returns:**
```typescript
{ success: true, objectId: 'obj-123', rotation: 45 }
```

---

## 7. Special Operations

### `replaceLogoPlaceholder(imageData: string, options?: ReplaceOptions): Promise<Result>`
Replace the logo placeholder in a layout with a custom image.

**Parameters:**
- `imageData`: Data URI or URL of the image
- `options` (optional):
  - `layoutId`: Specific layout ID (if multiple layouts loaded)
  - `preserveSize`: Keep placeholder dimensions (default: true)

**Returns:**
```typescript
{
  success: true,
  replaced: true,
  oldObjectId: 'logo-placeholder',
  newObjectId: 'logo-123'
}
```

### `updateText(objectId: string, newText: string): Promise<Result>`
Update text content of a text object.

**Parameters:**
- `objectId`: ID of text object (or identifying name like 'title-text')
- `newText`: New text content

**Returns:**
```typescript
{ success: true, objectId: 'text-123', text: 'New Text' }
```

### `searchAndReplace(search: string, replace: string, options?: SearchOptions): Promise<Result>`
Find and replace text across all text objects.

**Parameters:**
- `search`: Text to find
- `replace`: Replacement text
- `options` (optional):
  - `caseSensitive` (boolean): default false
  - `wholeWord` (boolean): default false

**Returns:**
```typescript
{
  success: true,
  replacements: 3,
  objectIds: ['text-1', 'text-2', 'text-3']
}
```

---

## 8. History Management

### `undo(): Promise<Result>`
Undo the last action.

**Returns:**
```typescript
{ success: true, message: 'Undo successful', historyIndex: 5 }
```

### `redo(): Promise<Result>`
Redo the last undone action.

**Returns:**
```typescript
{ success: true, message: 'Redo successful', historyIndex: 6 }
```

### `getHistoryState(): Promise<HistoryResult>`
Get history information.

**Returns:**
```typescript
{
  success: true,
  canUndo: true,
  canRedo: false,
  historyLength: 10,
  currentIndex: 9
}
```

---

## 9. Batch Operations

### `batchUpdate(operations: Operation[]): Promise<BatchResult>`
Execute multiple operations in a single call.

**Parameters:**
- `operations`: Array of operations to execute

**Example:**
```typescript
await window.thumbnailAPI.batchUpdate([
  { operation: 'addObject', params: { type: 'text', text: 'Title' } },
  { operation: 'addObject', params: { type: 'text', text: 'Subtitle' } },
  { operation: 'setBgColor', params: { color: 'light' } }
]);
```

**Returns:**
```typescript
{
  success: true,
  results: [
    { success: true, objectId: 'text-1' },
    { success: true, objectId: 'text-2' },
    { success: true, color: 'light' }
  ],
  total: 3,
  succeeded: 3,
  failed: 0
}
```

---

## 10. Search & Query

### `findObjects(query: ObjectQuery): Promise<ObjectList>`
Find objects matching specific criteria.

**Parameters:**
- `query`:
  - `type`: Object type filter
  - `text`: Text content search (for text objects)
  - `name`: Name/label search
  - `hasProperty`: Check for specific property existence
  - `bounds`: Search within bounds `{ x, y, width, height }`

**Returns:**
```typescript
{
  success: true,
  objects: [ /* matching objects */ ],
  count: 3
}
```

---

## 11. Download Operations

### `downloadCanvas(filename?: string, format?: string): Promise<Result>`
Trigger browser download of the canvas.

**Parameters:**
- `filename` (optional): Download filename (default: 'thumbnail.png')
- `format` (optional): `'png'` | `'jpeg'` (default: 'png')

**Returns:**
```typescript
{
  success: true,
  filename: 'my-thumbnail.png',
  format: 'png'
}
```

---

## Error Handling

All methods return a consistent error structure:

```typescript
{
  success: false,
  error: 'Error message',
  code: 'ERROR_CODE',  // e.g., 'OBJECT_NOT_FOUND', 'INVALID_PARAMETER'
  details: { /* additional context */ }
}
```

---

## Usage Examples

### Example 1: Create a Simple Thumbnail
```javascript
// Set canvas size
await window.thumbnailAPI.setCanvasSize('1200x675');

// Set background
await window.thumbnailAPI.setBgColor('#f0f0f0');

// Add title text
const title = await window.thumbnailAPI.addObject({
  type: 'text',
  text: 'My Awesome Thumbnail',
  fontSize: 72,
  fontFamily: 'Bison',
  bold: true,
  x: 100,
  y: 100
});

// Add a Huggy
await window.thumbnailAPI.addHuggy('huggy-chef', {
  x: 800,
  y: 300,
  width: 300,
  height: 300
});

// Export
const result = await window.thumbnailAPI.exportCanvas();
console.log(result.dataUrl); // Base64 image
```

### Example 2: Use a Layout and Customize
```javascript
// Load a layout
await window.thumbnailAPI.loadLayout('seriousCollab');

// Update title
await window.thumbnailAPI.updateText('title-text', 'HF x OpenAI Collaboration');

// Replace logo placeholder
await window.thumbnailAPI.replaceLogoPlaceholder('data:image/png;base64,...');

// Change background
await window.thumbnailAPI.setBgColor('light');

// Export
await window.thumbnailAPI.downloadCanvas('collaboration-thumbnail.png');
```

### Example 3: Search and Modify
```javascript
// Find all text objects
const texts = await window.thumbnailAPI.findObjects({ type: 'text' });

// Update all text to be bold
for (const obj of texts.objects) {
  await window.thumbnailAPI.updateObject(obj.id, { bold: true });
}

// Find objects by name
const logo = await window.thumbnailAPI.findObjects({ name: 'HF Logo' });
```

---

## Type Definitions

See `src/types/canvas.types.ts` for complete TypeScript type definitions.

---

## Implementation Status

✅ Fully Implemented
🚧 In Progress
📋 Planned

Current: All methods documented above are planned for implementation.