npm package: @foldingtext3/sdk
Description: Developer SDK for creating FoldingText extensions and themes
Author: Double Dog Software
Latest version: 3.0.0

# @foldingtext/sdk

Developer SDK for creating FoldingText 3 extensions, plugins, and themes.

## Install

```bash
npm install -g @foldingtext/sdk
```

## Quick Start

Create a new plugin:

```bash
create-ftplugin my-plugin --name "My Plugin" --desc "What it does"
```

This generates:

```
my-plugin.ftplugin/
  manifest.json   — plugin metadata
  main.js         — plugin code
  style.css       — custom styles
  README.md       — documentation
```

Install it by dragging the folder onto FoldingText's Extensions sidebar, or use `--install`:

```bash
create-ftplugin my-plugin --name "My Plugin" --install
```

## What's Included

- **`create-ftplugin`** — CLI tool to scaffold new plugins
- **`template/`** — starter template with all extension points documented
- **`docs/`** — complete API reference, getting started guide, examples, and distribution guide
- **`types/foldingtext.d.ts`** — TypeScript definitions for editor autocomplete

## Type Definitions

Add a `jsconfig.json` to your plugin for autocomplete in VS Code:

```json
{
  "compilerOptions": {
    "checkJs": true,
    "baseUrl": "."
  },
  "include": [
    "main.js",
    "node_modules/@foldingtext/sdk/types/*.d.ts"
  ]
}
```

Or add `// @ts-check` at the top of your `main.js`.

## Extension API

FoldingText plugins use the `Extensions` global to register callbacks:

```javascript
Extensions.addInit({
  identifier: PLUGIN_ID,
  handleEvent: (editor) => {
    // Plugin loaded
  },
  remove: () => {
    // Plugin disabled — clean up
  },
});

Extensions.addCommand({
  identifier: PLUGIN_ID,
  name: 'My Command',
  description: 'What this command does',
  keymap: 'Ctrl-Shift-M',
  performCommand: (editor) => {
    editor.replaceSelection('Hello!');
  },
});
```

### Available Extension Points

| Method | Fires When |
|--------|------------|
| `addInit` | Plugin loads |
| `addCommand` | User triggers command |
| `addEditorChange` | Text changes |
| `addTreeChanged` | Document tree re-syncs |
| `addSelectionDidChange` | Cursor/selection moves |
| `addRenderNode` | Node enters viewport |
| `addClockTick` | Every second |
| `addOption` | Persistent option |
| `addStyle` | Inject CSS |
| `addTheme` | Register theme |
| `addMode` | Register mode |

See `docs/extension-api.md` for the complete reference with all 25 extension points.

## Creating Themes

```javascript
Extensions.addTheme({
  identifier: PLUGIN_ID,
  name: 'My Theme',
  dark: false,
  colors: {
    bg: '#ffffff',
    fg: '#333333',
    caretColor: '#007AFF',
    selectionBg: '#a7caff',
    // ... 80+ color tokens available
  }
});
```

See `docs/extension-api.md` for the complete list of theme color tokens.

## Distribution

- **Manual** — share the `.ftplugin` folder or zip it
- **Deep link** — `x-ft://install-extension?id=com.example.myplugin&name=My%20Plugin`
- **Extension Library** — submit to extensions.foldingtext.com

See `docs/distribution.md` for details.

## Documentation

- [Getting Started](docs/getting-started.md)
- [Extension API Reference](docs/extension-api.md)
- [Examples & Patterns](docs/examples.md)
- [Distribution Guide](docs/distribution.md)

## Links

- [FoldingText](https://www.foldingtext.com)
- [Extension Library](https://extensions.foldingtext.com)
- [GitHub](https://github.com/FoldingText/foldingtext.next)