# @bobfrankston/msgerdefs

TypeScript definitions for the **msger** JavaScript API.

## Installation

```bash
npm install @bobfrankston/msgerdefs
```

## Usage

### TypeScript

```typescript
import type { MsgerAPI } from '@bobfrankston/msgerdefs';
import { isMsger, getMsgerAPI } from '@bobfrankston/msgerdefs';

// Option 1: Type the global window.msger
declare global {
    interface Window {
        msger?: MsgerAPI;
    }
}

// Check if running in msger
if (isMsger()) {
    window.msger!.setTitle('My Application');
    window.msger!.saveData('lastOpened', new Date().toISOString());
}

// Option 2: Use getMsgerAPI() for cross-platform compatibility
const msger = getMsgerAPI();
msger.saveData('userPrefs', { theme: 'dark' });  // Works in both msger and browser!
msger.setTitle('My App');  // Only works in msger, no-op in browser
```

### JavaScript

```javascript
import { isMsger, getMsgerAPI } from '@bobfrankston/msgerdefs';

const msger = getMsgerAPI();

// Data persistence (works in both msger and browser)
msger.saveData('userSettings', { fontSize: 14, theme: 'dark' });
const settings = msger.loadData('userSettings', { fontSize: 12 });

// Window control (msger only, gracefully degrades in browser)
if (isMsger()) {
    msger.toggleFullscreen();
    msger.setAlwaysOnTop(true);
}
```

## API Reference

### Window Control

- `toggleFullscreen()` - Toggle fullscreen mode
- `setFullscreen(enabled: boolean)` - Set fullscreen state
- `minimize()` - Minimize window
- `maximize()` - Toggle maximize/restore
- `setSize(width, height)` - Set window size
- `setPosition(x, y)` - Set window position
- `setAlwaysOnTop(enabled: boolean)` - Keep window on top
- `setTitle(title: string)` - Set window title
- `close(result?)` - Close window with optional result

### Data Persistence

- `saveData(key, value)` - Save data to localStorage
- `loadData(key, defaultValue?)` - Load data from localStorage
- `removeData(key)` - Remove data
- `clearData()` - Clear all msger data

### File System (Coming Soon)

- `fs.selectFile(options?)` - Open file picker
- `fs.selectFiles(options?)` - Open multi-file picker
- `fs.saveFileAs(content, filename?, options?)` - Save file dialog
- `fs.selectFolder(options?)` - Folder picker
- `fs.read(path)` - Read file (requires allowFs flag)
- `fs.write(path, content)` - Write file (requires allowFs flag)
- `fs.list(path)` - List directory (requires allowFs flag)
- `fs.exists(path)` - Check if file exists (requires allowFs flag)
- `fs.delete(path)` - Delete file (requires allowFs flag)

## Examples

See [samples.html](samples.html) for interactive examples and demos of all API features!

**Test in msger:**
```bash
msger -url "file:///path/to/node_modules/@bobfrankston/msgerdefs/samples.html"
```

**Test in browser:**
```bash
# Open samples.html in your browser to test browser compatibility
```

The samples demonstrate:
- Window control (fullscreen, minimize, maximize, resize, position)
- Data persistence (save/load user preferences, session data, recent files)
- Presentation mode example
- Session management
- And more!

## Browser Compatibility

The `getMsgerAPI()` function returns a browser-compatible implementation:

- **Data persistence**: Uses localStorage in both msger and browser
- **Window control**: No-op in browser (except `setTitle` updates document.title)
- **File system**: Not available in browser (`fs` is undefined)

This allows you to write code once that works in both environments!

## License

ISC
