# FurryPlace Plugins System

The FurryPlace SDK provides an extensible plugin system that allows you to add custom buttons and functionality to the UI without modifying the core codebase.

## Quick Start

### Development (Local)

1. Add your plugin file to `frontend-backup/plugins/`:
   ```bash
   # Example: Create a custom button plugin
   cat > frontend-backup/plugins/my-plugin.js << 'EOF'
   (function() {
     function waitForSDK(callback) {
       if (window.FurryPlaceSDK) {
         callback();
       } else {
         setTimeout(() => waitForSDK(callback), 100);
       }
     }

     waitForSDK(() => {
       window.FurryPlaceSDK.registerButton({
         id: 'my-button',
         title: 'My Custom Button',
         position: 'bottom',
         icon: '<svg>...</svg>',
         onClick: () => alert('Clicked!')
       });
     });
   })();
   EOF
   ```

2. Refresh your browser - the plugin loads automatically!

### Production (Docker)

When using `USE_FRONTEND_BACKUP=true`:

1. **Before building the Docker image**, add plugins to `frontend-backup/plugins/`
2. Build the image:
   ```bash
   docker build --build-arg USE_FRONTEND_BACKUP=true -t furryplace .
   ```
3. The plugins will be included in the image automatically

When using the regular frontend build (not `USE_FRONTEND_BACKUP`):

1. Create a `frontend-src/public/plugins/` directory
2. Add your plugin files there
3. Build normally - the plugins will be copied to the final build

### Runtime Plugin Loading (Docker Volume)

You can also mount a plugins directory at runtime to add/update plugins without rebuilding:

```bash
docker run -d \
  -v ./my-plugins:/app/frontend/plugins \
  -e USE_FRONTEND_BACKUP=false \
  furryplace
```

Or with docker-compose:

```yaml
services:
  furryplace:
    image: furryplace
    volumes:
      - ./my-plugins:/app/frontend/plugins
    environment:
      USE_FRONTEND_BACKUP: "false"
```

## How It Works

1. **Backend**: The `/api/plugins` endpoint (in `src/routes/plugins.ts`) scans the plugins directory and returns a list of `.js` files
2. **Frontend**: The SDK (`furryplace-sdk.js`) automatically fetches this list and dynamically loads each plugin
3. **Plugins**: Each plugin registers buttons or functionality using the SDK API

## Plugin Development

See the full documentation in [frontend-backup/plugins/README.md](frontend-backup/plugins/README.md) for:
- SDK API reference
- Button configuration options
- Example plugins
- Troubleshooting tips

## Environment Variables

The plugin system respects the `USE_FRONTEND_BACKUP` environment variable:
- `USE_FRONTEND_BACKUP=true` → Loads from `frontend-backup/plugins/`
- `USE_FRONTEND_BACKUP=false` → Loads from `frontend/plugins/`

This is automatically handled by the backend routes.

## Disabling Plugins

To disable a plugin without deleting it:
1. Rename it to anything that doesn't end in `.js` (e.g., `my-plugin.js.disabled`)
2. Refresh the page

The SDK only loads files ending in `.js`.

## Security Notes

- Plugins have full access to the browser's JavaScript environment
- Only load plugins from trusted sources
- Consider reviewing plugin code before deployment
- Plugins run in the same origin as your application

## Examples

Example plugins are included in `frontend-backup/plugins/example-button.js`:
- Help button with tooltip
- Debug info button
- Conditional rendering example
- External link button (Discord)

To try them out:
1. The example plugin is automatically loaded
2. Check the browser console for loading messages
3. Look for the new buttons in the UI