PPTClaw

PPTClaw is a local-first presentation editor. Decks are JSON files on disk — you create and edit them directly, and the editor syncs changes live via WebSocket.

## Setup

If `pptclaw` is not installed, install it globally:
```bash
pnpm add -g pptclaw    # or: npm install -g pptclaw
```

## Deck Format

A deck is a folder with this structure:

```
my-deck/
├── manifest.json           # Title, theme, viewport, slide order
├── slides/
│   ├── 001-abc123.json     # Slide files: <NNN>-<id>.json
│   ├── 002-def456.json
│   └── ...
└── assets/                 # Images and other media
    ├── hero.jpg
    └── ...
```

### manifest.json

```json
{
  "title": "My Presentation",
  "format": "1",
  "viewport": { "width": 1920, "ratio": 0.5625 },
  "theme": {
    "primary": "#2563eb",
    "secondary": "#7c3aed",
    "tx1": "#1e293b",
    "accents": ["#2563eb", "#7c3aed", "#5b9bd5", "#ff6b6b", "#4ecdc4", "#95e1d3"],
    "fontHeading": "YouSheBiaoTiHei",
    "fontBody": "Microsoft YaHei"
  }
}
```

- `viewport.ratio` is height/width (0.5625 = 16:9, giving 1920x1080)
- `theme.accents` is an array of 6 colors used sequentially for chart series, infographic items, etc.

### Slide JSON

Each slide file contains one slide object:

```json
{
  "id": "abc123",
  "elements": [ /* PPTElement objects */ ],
  "background": { "type": "solid", "color": "#ffffff" },
  "remark": "Speaker notes text",
  "type": "content"
}
```

- `type`: "cover", "contents", "transition", "content", "end"
- `elements`: array of typed element objects (see below)
- `background`: optional, defaults to white
- `remark`: optional speaker notes (plain text)

## Canvas

- Size: **1920 x 1080 pixels**
- Origin: top-left corner (0, 0)
- All position/size values are in pixels

## Base Element Fields

Every element shares these fields:

```ts
id: string        // Unique element ID
left: number      // X position (px from left edge)
top: number       // Y position (px from top edge)
width: number     // Element width (px)
height: number    // Element height (px)
rotate: number    // Rotation in degrees, default 0
lock?: boolean    // Lock element from editing
groupId?: string  // Elements with same groupId form a group
name?: string     // Display name
link?: { type: 'web' | 'slide', target: string }
```

Exception: `line` elements omit `height` and `rotate` — they use start/end points instead.

## Theme Colors

Use CSS variable references instead of hardcoded hex values to stay consistent with the deck's theme:

| Variable | Purpose |
|----------|---------|
| `var(--primary)` | Primary brand color |
| `var(--secondary)` | Secondary/accent color |
| `var(--tx1)` | Text color |
| `var(--accent1)` to `var(--accent6)` | Chart/emphasis colors |

**Brightness variants** — append a suffix to any theme variable:
- `var(--primary-plus-50)` — lighter (+50 brightness)
- `var(--primary-minus-25)` — darker (-25 brightness)
- Works for all theme colors: secondary, tx1, accent1-6

**Theme fonts:**
- `var(--font-heading)` — for titles, subtitles, headers
- `var(--font-body)` — for body text, content, items

## Common Style Types

### Outline (border)
```ts
{ style?: 'solid' | 'dashed' | 'dotted', width?: number, color?: string }
```

### Shadow
```ts
{ offset: number, angle: number, blur: number, color: string, alpha: number }
// offset: 0-100, angle: 0-359, blur: 0-100 (pt), alpha: 0-100 (0=transparent)
```

### Gradient
```ts
{
  type: 'linear' | 'radial',
  colors: [{ pos: number, color: string, alpha?: number }],  // pos: 0-100%
  rotate?: number,
  radialStart?: 'center' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
}
```

## Text Element (Inline Reference)

Text is the most common element type, so its full schema is included here. For other element types, run `pptclaw element-docs <type>`.

```ts
interface PPTTextElement extends PPTBaseElement {
  type: 'text'
  content: string           // ProseMirror HTML
  defaultColor: string      // Fallback color (overridden by inline HTML styles)
  fill?: string             // Background fill color
  lineHeight?: number       // Line height multiplier, default 1.5
  wordSpace?: number        // Letter spacing, default 0
  paragraphSpace?: number   // Paragraph spacing (px), default 5
  opacity?: number          // 0-1, default 1
  vertical?: boolean        // Vertical text mode
  outline?: Outline
  shadow?: Shadow
  textType?: 'title' | 'subtitle' | 'content' | 'item' | 'itemTitle' | 'notes' | 'header' | 'footer'
}
```

### HTML Content Format

The `content` field uses ProseMirror HTML with inline styles:

```html
<p style="font-size: 72px; font-family: var(--font-heading); font-weight: bold;">Title Text</p>
<p style="font-size: 36px; font-family: var(--font-body);">Body paragraph</p>
```

Supported inline styles: `font-size` (px), `color`, `font-weight`, `font-style`, `text-decoration`, `text-align`, `font-family`.

### Font Size Rules

Font sizes in HTML are in **px**, which equals **2x the PowerPoint pt value**. This matters because presentations are viewed on large screens — small text becomes unreadable.

| Role | Pt | Px | Notes |
|------|----|----|-------|
| Title | 36pt | 72px | Minimum for slide titles |
| Subtitle | 24pt | 48px | |
| Body | 18pt | 36px | Recommended 36-40px |
| Minimum | 16pt | 32px | Nothing smaller than this |

Common mistake: using web-scale sizes like 14px, 16px, 18px — these are too small for presentations.

## Slide Background

```json
{
  "background": {
    "type": "solid",
    "color": "var(--primary-plus-80)"
  }
}
```

Types: `"solid"` (with `color`) or `"gradient"` (with `gradient` object). Set backgrounds on the slide object, not by creating a full-canvas shape.

## Layout Conventions

### Standard Content Page
- **Title**: left: 80, top: 80, font-size: 72px, bold
- **Content area**: left: 80, top: 200, width: 1760, height: 800
- Large elements (charts, infographics, tables) should fill the content area when shown alone

### Centering
To horizontally center an element: `left = (1920 - width) / 2`

Note: `left: 960` does NOT center — it places the element's left edge at the midpoint, pushing it right.

### Layout Self-Check

Before finalizing element positions, verify:
1. **No overlap** — element rectangles don't unintentionally intersect
2. **Readable text** — all font sizes >= 32px, content fits within element bounds
3. **Edge margins** — elements stay >= 60px from canvas edges
4. **Element spacing** — >= 20px gap between elements
5. **Consistency** — use 20px card gap and 10px border-radius across all slides

## Element Types

Beyond the text element documented above, PPTClaw supports these element types:

| Type | Description | Key Fields |
|------|-------------|------------|
| `image` | Image with cover/fill, clipping, masking | imageSource, fit, clipShape, mask |
| `shape` | Vector shape with optional inner text | shapeId, fill, gradient, text |
| `line` | Line/arrow/connector (no height/rotate) | start, end, points, width (stroke) |
| `chart` | Data visualization (8 chart types) | chartType, data, color |
| `table` | Grid table with styled cells | data (2D TableCell), colWidths, theme |
| `icon` | SVG icon by keyword search | keyword, color |
| `artText` | Decorative wave text (cover pages only) | content, style, defaultColor |
| `infographic` | Template-based infographic/diagram | template, data, color |

Get the full schema for any type:
```bash
pptclaw element-docs <type>           # e.g., pptclaw element-docs image
pptclaw element-docs chart table      # multiple types at once
pptclaw element-docs                  # list all types
```

## CLI Reference

All commands support `-p, --port <port>` (default: 3059).

### pptclaw serve [deck]
Start the editor server as a background daemon. Optionally open a deck immediately.
```bash
pptclaw serve                    # start server
pptclaw serve ./my-deck          # start and open deck
pptclaw serve --port 4000        # custom port
```
Exit code: 0 on success, 1 if server fails to start.

### pptclaw open \<path\>
Open a deck folder in the running editor.
```bash
pptclaw open ./my-deck
pptclaw open ./my-deck --session custom-id
```
Output: session ID, path, slide count.

### pptclaw validate \<path\>
Validate a deck folder structure and content. Returns JSON with `valid`, `errors`, `warnings`.
```bash
pptclaw validate ./my-deck
```
Exit code: 0 if valid, 1 if errors found. Requires running server.

### pptclaw list-decks
List active sessions (open decks) with slide counts.
```bash
pptclaw list-decks
```

### pptclaw status
Show server status, auth state, and active sessions as JSON.

### pptclaw init
Copy the PPTClaw skill file to `.claude/skills/pptclaw/SKILL.md` in the current directory.

### pptclaw element-docs [type...]
Print element type documentation.
```bash
pptclaw element-docs              # list available types
pptclaw element-docs image        # print image element docs
pptclaw element-docs chart table  # print multiple
```

### pptclaw search-images \<query\>
Search Unsplash images. Returns JSON array of results with id, description, dimensions.

### pptclaw download-image \<url\> --deck \<path\>
Download an image to a deck's assets folder.

## Workflows

### Create a New Deck

1. Create the folder structure:
   ```bash
   mkdir -p my-deck/slides my-deck/assets
   ```

2. Write `manifest.json` with title, theme, and viewport

3. Create slide files in `slides/` (numbered: `001-<id>.json`, `002-<id>.json`, ...)

4. Validate:
   ```bash
   pptclaw validate ./my-deck
   ```

5. Open in editor:
   ```bash
   pptclaw serve ./my-deck
   ```

### Edit an Existing Slide

1. Read the slide JSON file
2. Modify the `elements` array — add, update, or remove elements
3. Write the file back — the editor picks up changes automatically via file watcher
4. Validate if needed: `pptclaw validate ./my-deck`

### Add Images

1. Search for images:
   ```bash
   pptclaw search-images "mountain landscape"
   ```
2. Download to deck assets:
   ```bash
   pptclaw download-image <url> --deck ./my-deck
   ```
3. Reference in slide JSON via `imageSource` field on an image element