initial draft

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4.1.0
+        with:
+          version: 10.7.1
+
+      - name: Set node LTS
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: pnpm
+
+      - name: Install
+        run: pnpm install
+
+      - name: Build
+        run: pnpm build
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Format
+        run: pnpm format:check
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Test
+        run: pnpm test

.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+permissions:
+  contents: write
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4.1.0
+        with:
+          version: 10.7.1
+
+      - name: Set node LTS
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          cache: pnpm
+
+      - run: npx changelogithub
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

.nvmrc

@@ -0,0 +1 @@
+24.6

.vscode/settings.json

@@ -0,0 +1,16 @@
+{
+	"[json]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[typescript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"editor.codeActionsOnSave": {
+		"source.fixAll": "explicit",
+		"source.sortMembers": "explicit"
+	},
+	"editor.defaultFormatter": "biomejs.biome",
+	"editor.formatOnSave": true,
+	"editor.formatOnPaste": true,
+	"editor.formatOnSaveMode": "file"
+}

AGENTS.md

@@ -0,0 +1,44 @@
+# Mirage SDK - Coding Agent Guidelines
+
+## Build/Test Commands
+- `pnpm build` - Build the project using tsdown
+- `pnpm dev` - Watch mode for development  
+- `pnpm dev:example` - Run Vite dev server for examples
+- `pnpm test` - Run all tests with Vitest
+- `pnpm test tests/specific.test.ts` - Run a single test file
+- `pnpm typecheck` - Type check with TypeScript (no emit)
+- `pnpm format` - Format code with Biome
+- `pnpm release` - Bump version and publish to NPM
+
+## Project Architecture
+- **src/index.ts** - Main entry point, exports createMirageClient
+- **src/realtime/** - WebRTC real-time video streaming logic
+  - `client.ts` - Real-time client implementation with WebRTC connection management
+  - `webrtc-manager.ts` - WebRTC connection lifecycle and signaling
+  - `webrtc-connection.ts` - Low-level WebRTC peer connection handling
+  - `types.ts` - TypeScript types for WebRTC messages and events
+- **src/utils/** - Shared utilities
+  - `errors.ts` - Error factory pattern with ERROR_CODES constants
+- **tests/** - Test files using Vitest (.test.ts extension)
+- **dist/** - Build output (gitignored, generated by tsdown)
+
+## Code Style & Conventions
+- **TypeScript**: Strict mode, no unused locals, verbatimModuleSyntax enabled
+- **Module System**: ESM only (`type: "module"`), platform neutral builds via tsdown
+- **Build Tool**: tsdown with unbundle mode for better tree-shaking
+- **Testing**: Vitest for unit tests
+- **Imports**: Named exports preferred, use `export type` for types, no file extensions needed
+- **Error Handling**: Use error factory pattern (createMirageError), include ERROR_CODES constants
+- **Validation**: Use Zod schemas for runtime validation (e.g., mirageClientOptionsSchema)
+- **WebRTC**: Implement proper connection lifecycle with error recovery
+- **Events**: Use mitt for typed event emitters (connection state, errors)
+- **Formatting**: Use Biome formatter (`pnpm format`), enforced formatting standards
+- **Dependencies**: 
+  - Runtime: mitt (events), p-retry (resilience), uuid (unique IDs), zod (validation)
+  - Dev: tsdown (build), vitest (test), typescript, vite (examples), bumpp (releases)
+
+## API Design Patterns
+- **Factory Functions**: Use `create*` pattern for constructors (createMirageClient, createRealTimeClient)
+- **Options Validation**: Validate all public API options with Zod schemas
+- **Error Messages**: Provide clear, actionable error messages with specific error codes
+- **Type Exports**: Export all public types alongside implementations