# Changelog

All notable changes to `@materi.ai/frame` will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.0.0-rc.1] - 2025-12-24 - 🚀 **Release Candidate**

**🎯 Production-ready release candidate:** `npm install @materi.ai/frame@rc`

### Major Improvements

#### 📚 Complete Documentation Ecosystem (TASKSET 7)

- **Comprehensive API Documentation**: TypeDoc integration with automated generation from TypeScript source
- **Progressive Tutorial Series**: 9 tutorials from beginner to advanced (6+ hours of content)
- **Real-World Examples**: Collaborative editor, spreadsheet calculator, component showcase
- **15-Minute Quick Start**: Get running immediately with copy-paste examples
- **Contributing Guidelines**: Complete development workflow and quality standards

#### 🔧 Production Release Readiness (TASKSET 8)

- **npm Publication Setup**: Complete registry configuration with automated publishing
- **Release Automation**: Version management, changelog generation, and release workflows
- **Quality Assurance**: Comprehensive testing, bundle validation, and integrity checks
- **Monitoring Integration**: Download tracking, analytics, and error monitoring setup

**🎉 Now available on npm:** `npm install @materi.ai/frame`

**BREAKING:** This is the first stable release ready for npm publication. The API is now considered stable and production-ready.

### 📦 Package Distribution

- **Published to npm**: Available as `@materi.ai/frame` with full TypeScript support
- **Tree-shakeable**: ESM modules with optimized bundling (`sideEffects: false`)
- **Supply chain security**: npm provenance enabled for verified builds
- **Unified exports**: Single package with subpath exports for all modules
- **Documentation complete**: README, API reference, examples, and troubleshooting

### Added

#### Core Package

- **Operational Transformation Engine** — Complete OT algorithm implementation with:
    - `applyOp()` — Apply operations to document state
    - `transform()` — Transform operations for concurrent edits
    - `compose()` — Compose multiple operations
    - Full support for string, array, and object mutations
- **Formula Engine** — Spreadsheet formula parsing and evaluation:
    - `parseFormula()` — Parse formula expressions
    - `evaluateFormula()` — Evaluate formulas with cell references
    - Support for basic and advanced functions (SUM, AVERAGE, IF, CONCAT, etc.)
    - Type-safe formula results

- **Type System** — Comprehensive TypeScript definitions:
    - Document types (Cell, Sheet, Document, etc.)
    - Operation types (Insert, Delete, Replace)
    - User and collaboration types
    - Formula and editor types

- **WebSocket Manager** — Real-time connection handling:
    - `WebSocketManager` class for connection lifecycle
    - Message serialization/deserialization
    - Automatic reconnection with exponential backoff
    - Heartbeat/ping-pong support

- **Presence System** — User presence and cursor tracking:
    - Track active users and their cursors
    - Broadcast user activity
    - Presence list management

- **Auth System** — Authentication and permission models:
    - User authentication flows
    - Permission checking
    - Session management types

- **Undo/Redo Manager** — Command-based undo/redo:
    - `UndoManager` class for command history
    - Undo/redo stack management
    - Grouped commands support

- **Search Infrastructure** — Full-text search support:
    - Search query parsing
    - Result ranking
    - Index building

#### UI Package

- **Design Tokens** — Complete token system:
    - Color palette (semantic and raw colors)
    - Typography scale (fonts, sizes, weights, line heights)
    - Spacing scale (consistent 4px-based spacing)
    - Shadow system (elevation levels)
    - Border radius and widths
    - Transition timings and animations
    - Dark mode support

- **Primitive Components** — Accessible, unstyled base components:
    - `Button` — Button with variants (primary, secondary, danger)
    - `Input` — Text input with validation states
    - `Select` — Dropdown select with keyboard support
    - `Checkbox` — Accessible checkbox
    - `Radio` — Radio button group
    - `Dialog` — Modal dialog component
    - `Tabs` — Tab navigation
    - `Spinner` — Loading indicator
    - `Badge` — Status badge
    - `Toast` — Toast notification
    - `Avatar` — User avatar with initials fallback

- **High-Level Components**:
    - `CollaborationUI` — Collaborative editing interface
    - `CommandPalette` — Command/search interface
    - `ErrorBoundary` — Error handling wrapper

- **Editor Components**:
    - `RichTextEditor` — Rich text editing interface
    - `SpreadsheetEditor` — Spreadsheet interface
    - `PresentationEditor` — Presentation editing interface

- **Theme System**:
    - Light and dark theme support
    - `useTheme()` hook for theme switching
    - Semantic color tokens
    - CSS-in-JS and vanilla CSS compatible

#### Hooks Package

- **`useOT()`** — Manage operational transformation state
    - Apply operations to local state
    - Track pending operations
    - Handle operation composition

- **`useOTSync()`** — Synchronize OT state across clients
    - Broadcast operations to server
    - Apply remote operations locally
    - Handle concurrent edits

- **`useWebSocket()`** — WebSocket connection management
    - Connect/disconnect lifecycle
    - Send and receive messages
    - Connection state tracking
    - Auto-reconnection

- **`useAuth()`** — Authentication state management
    - User session tracking
    - Login/logout flows
    - Permission checking

- **`useFetch()`** — Type-safe HTTP requests
    - GET, POST, PUT, DELETE support
    - Request caching
    - Error handling

- **`useCommandPalette()`** — Command palette state
    - Open/close state
    - Command search and filtering
    - Command execution

- **`useUndoRedo()`** — Undo/redo functionality
    - Track command history
    - Undo and redo operations
    - History state exposure

- **`useLocalStorage()`** — Persistent local state
    - Sync with localStorage
    - Type-safe storage access
    - Automatic serialization

- **`useForm()`** — Form state management
    - Field state tracking
    - Validation support
    - Form submission handling

- **`usePerformance()`** — Performance monitoring
    - Render time tracking
    - Memory usage monitoring
    - Performance metrics export

#### API Package

- **HTTP Client** — Lightweight typed HTTP client:
    - `createClient()` — Initialize HTTP client
    - Request interceptors
    - Response interceptors
    - Error handling

- **Endpoint Definitions** — Pre-defined typed API routes:
    - Document management endpoints
    - User endpoints
    - Workspace endpoints
    - Collaboration endpoints

- **Result Type** — Type-safe API responses:
    - Discriminated union for success/error
    - Type inference for response data

### Architecture

- **Monorepo with Turbo** — Fast, cached builds with `turbo`
- **TypeScript 5.3+** — Strict mode, full type safety
- **ESM + CommonJS** — Dual module format
- **Zero Runtime Dependencies** — Only React peer dependency
- **Tree Shakeable** — Unused code eliminated by bundlers
- **Distributed Types** — Full `.d.ts` generation
- **Source Maps** — Debug-friendly source maps

### Documentation

- Comprehensive README with quick start guide
- API documentation for all packages
- Architecture highlights and design patterns
- Development guide and testing setup
- Troubleshooting section

---

## Versioning Strategy

### Major Version (1.x.y)

- Breaking changes to public API
- Major architectural changes
- New major features

### Minor Version (x.1.y)

- New features (backward compatible)
- New components or hooks
- API additions

### Patch Version (x.y.1)

- Bug fixes
- Performance improvements
- Documentation updates
- Internal refactorings

### Pre-release Versions

- `1.0.0-alpha.1` — Early development
- `1.0.0-beta.1` — Feature complete, testing phase
- `1.0.0-rc.1` — Release candidate

---

## Release Process

1. **Update Version Numbers**

    ```bash
    npm version major|minor|patch
    ```

2. **Update CHANGELOG** — Document changes in this file

3. **Build & Test**

    ```bash
    pnpm build
    pnpm test
    pnpm type-check
    ```

4. **Publish**

    ```bash
    npm publish
    ```

5. **Tag Release**
    ```bash
    git tag v1.0.0
    git push origin v1.0.0
    ```

---

## Unreleased Changes

### Planned Features

- [ ] Official Storybook component gallery
- [ ] GraphQL client integration
- [ ] Offline-first synchronization strategy
- [ ] Advanced formula functions (financial, statistical)
- [ ] Rich text editor with collaborative cursors
- [ ] End-to-end encryption support
- [ ] Performance monitoring dashboard
- [ ] Mobile-optimized components

### Under Investigation

- CRDT (Conflict-free Replicated Data Type) support
- Lazy loading and code splitting optimizations
- Custom rendering engines for editors
- Plugin system for extensibility

---

## Deprecation Policy

Deprecated features will:

1. Be marked with `@deprecated` JSDoc comments
2. Receive at least 2 minor version cycles of support
3. Be removed in the next major version
4. Include migration guides in documentation

---

## Known Limitations

- Formula engine supports subset of Excel functions (expanding in minor versions)
- WebSocket client requires TLS in production (http:// not supported)
- Presence system limited to 1000 concurrent users per document
- Search index limited to 1M documents (per session)

---

## Contributing

See [Contributing Guide](../CONTRIBUTING.md) for development setup, commit message conventions, and pull request process.

---

**For more information, see [README.md](./README.md) and the [API Documentation](./docs/).**