feat(apps/playground): add modular online collaborative editor

.claude/CLAUDE.md

@@ -2,6 +2,12 @@
 
 This file contains specific instructions for Claude AI when working on the Softmaple codebase.
 
+## CRITICAL RULES - NEVER VIOLATE
+
+1. **NEVER use `--no-verify` flag when committing** - Pre-commit hooks are essential for code quality. If hooks fail, fix the issues and retry without bypassing.
+2. **NEVER commit directly to `next` branch** - Always create a feature branch first.
+3. **ALWAYS request user approval before commits/pushes** - No exceptions.
+
 ## Project Overview
 
 Softmaple is a Turborepo monorepo containing:
@@ -246,7 +252,15 @@ docs: update functional programming guidelines
 2. Run tests: \`pnpm --filter <package> test\`
 3. Run linter: \`pnpm lint\`
 4. Format code: \`pnpm format\`
-5. **Request user approval before pushing**
+5. **NEVER use `--no-verify` flag** - Pre-commit hooks ensure code quality and must not be bypassed
+6. **Request user approval before pushing**
+
+### Adding shadcn UI Components
+
+To add shadcn UI components in the turbo repo, run the `add` command in the path of the app:
+```bash
+pnpm dlx shadcn@latest add [COMPONENT]
+```
 
 ## Package-Specific Guidelines
 

AGENTS.md

@@ -85,6 +85,27 @@ const withLogging =
 - Run tests before merging
 - Regenerate Prisma after schema changes
 
+## Pre-commit Hooks and Code Quality
+
+**CRITICAL: Never use `--no-verify` flag when committing code.** Pre-commit hooks run essential quality checks including:
+- Code formatting with Prettier/Biome
+- Linting with ESLint
+- Type checking
+
+If pre-commit hooks fail, you must:
+1. Fix the issues (run `pnpm format` or `npx biome check --write`)
+2. Stage the fixes
+3. Retry the commit WITHOUT `--no-verify`
+
+Bypassing these checks undermines code quality safeguards and is unacceptable.
+
+## Adding shadcn UI Components
+
+To add shadcn UI components in the turbo repo, run the `add` command in the path of the app:
+```bash
+pnpm dlx shadcn@latest add [COMPONENT]
+```
+
 ## Commit & Pull Request Guidelines
 
 **Commits:** `type(scope): summary`
@@ -94,6 +115,7 @@ const withLogging =
 - **Branch naming:** `feature-name-$(date +%s)`
 - **IMPORTANT: Never commit directly to the `next` branch.** Always create a new feature branch before making changes if you are on the default `next` branch.
 - **When switching back to `next` from a feature branch:** Always run `git pull` and `pnpm i` to sync with remote and update dependencies
+- **NEVER use `--no-verify` flag when committing** - Pre-commit hooks are critical for code quality and must not be bypassed. Work through any formatting or linting issues instead.
 - **Always request user approval before commits/pushes**
 
 **PRs:** Include summary, test commands, screenshots for UI changes

apps/playground/AGENTS.md

@@ -0,0 +1,140 @@
+# Playground App Development Guidelines
+
+This file contains instructions for AI agents and developers working on the Playground application.
+
+## Code Formatting and Linting
+
+This app uses **Biome** for code formatting and linting. Use these commands to maintain code quality:
+
+### Biome Command Reference
+
+```bash
+# Format all files
+pnpm exec biome format --write
+
+# Format specific files
+pnpm exec biome format --write <files>
+
+# Lint and apply safe fixes to all files
+pnpm exec biome lint --write
+
+# Lint files and apply safe fixes to specific files
+pnpm exec biome lint --write <files>
+
+# Format, lint, and organize imports of all files
+pnpm exec biome check --write
+
+# Format, lint, and organize imports of specific files
+pnpm exec biome check --write <files>
+```
+
+### Usage Guidelines
+
+#### When to use `biome format`
+- Fixing indentation and spacing issues
+- Correcting quote styles (single vs double)
+- Fixing line endings and trailing commas
+
+#### When to use `biome lint`
+- Fixing code quality issues
+- Applying best practices
+- Removing unused imports
+- Fixing potential bugs
+
+#### When to use `biome check`
+- Before committing (comprehensive check)
+- After refactoring
+- When you want to fix everything at once
+
+## Pre-commit Hook Troubleshooting
+
+If pre-commit hooks fail:
+
+```bash
+# 1. Check what files have issues
+git status
+
+# 2. Fix all staged files
+pnpm exec biome check --write $(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(ts|tsx|js|jsx)$')
+
+# 3. Stage the fixes
+git add -u
+
+# 4. Retry commit (NEVER use --no-verify)
+git commit -m "your message"
+```
+
+## Project Structure
+
+```
+apps/playground/
+├── src/
+│   ├── components/     # Reusable UI components
+│   ├── hooks/         # Custom React hooks
+│   ├── modules/       # Feature modules (keep small, <200 lines)
+│   ├── routes/        # TanStack Router pages
+│   ├── lib/           # Utility functions
+│   └── test/          # Unit tests
+├── e2e/               # Playwright E2E tests
+└── public/            # Static assets
+```
+
+## Development Commands
+
+```bash
+# Development
+pnpm --filter playground dev     # Start dev server
+pnpm --filter playground build   # Build for production
+pnpm --filter playground preview # Preview production build
+
+# Testing
+pnpm --filter playground test           # Run unit tests
+pnpm --filter playground test:coverage  # Run tests with coverage
+pnpm --filter playground test:e2e       # Run E2E tests
+
+# Type checking
+pnpm --filter playground typecheck
+```
+
+## Code Style Guidelines
+
+1. **Functional Programming**: Prefer pure functions, immutability, and function composition
+2. **TypeScript**: No `any` types, use proper type definitions
+3. **Async Operations**: Always handle promises properly with async/await
+4. **ID Generation**: Use `crypto.randomUUID()` for secure IDs
+5. **Module Size**: Keep files under 200 lines, split large modules
+6. **Imports**: Use direct imports, avoid barrel exports (index.ts)
+
+## Common Issues and Solutions
+
+### Biome Formatting Issues
+```bash
+# Quick fix for all formatting issues
+pnpm exec biome format --write src/
+```
+
+### Biome Linting Issues
+```bash
+# Apply safe auto-fixes
+pnpm exec biome lint --write src/
+```
+
+### Import Organization Issues
+```bash
+# Organize imports automatically
+pnpm exec biome check --write src/
+```
+
+### TypeScript Errors
+```bash
+# Check for type errors
+pnpm --filter playground typecheck
+```
+
+## Important Notes
+
+- **NEVER use `--no-verify` flag** when committing - always fix issues properly
+- **DO NOT use `pnpm dev`** directly - use `pnpm --filter playground dev`
+- Biome configuration is in `biome.json` at the project root
+- Pre-commit hooks will run Biome automatically on staged files
+- If Biome and Prettier conflict, Biome takes precedence in this project

apps/playground/CLAUDE.md

@@ -0,0 +1,99 @@
+# Claude AI Guidelines for Playground App
+
+This file contains specific instructions for Claude AI when working on the Playground application.
+
+## Overview
+
+The Playground app is a Vite + React application for demonstrating various features and experiments. It uses:
+- **Vite** for building and development
+- **React** with TypeScript
+- **TanStack Router** for routing
+- **Biome** for formatting and linting
+- **Vitest** for unit testing
+- **Playwright** for E2E testing
+
+## Code Formatting and Linting
+
+The Playground app uses **Biome** for code formatting and linting. Always use these commands instead of global pnpm commands:
+
+### Biome Commands
+
+```bash
+# Format all files
+pnpm exec biome format --write
+
+# Format specific files
+pnpm exec biome format --write <files>
+
+# Lint and apply safe fixes to all files
+pnpm exec biome lint --write
+
+# Lint files and apply safe fixes to specific files
+pnpm exec biome lint --write <files>
+
+# Format, lint, and organize imports of all files
+pnpm exec biome check --write
+
+# Format, lint, and organize imports of specific files
+pnpm exec biome check --write <files>
+```
+
+### When to Use Each Command
+
+- **`biome format`**: When you only need to fix formatting issues (indentation, spacing, etc.)
+- **`biome lint`**: When you need to fix linting issues (code quality, best practices)
+- **`biome check`**: When you want to do everything at once (format + lint + organize imports)
+
+## Pre-commit Hook Issues
+
+If pre-commit hooks fail with Biome errors:
+
+1. Run `pnpm exec biome check --write` on the staged files
+2. Stage the fixed files: `git add <fixed-files>`
+3. Retry the commit **WITHOUT using `--no-verify`**
+
+## Module Organization
+
+- Keep modules under `src/modules/` for feature-specific code
+- Keep components under `src/components/` for reusable UI
+- Keep hooks under `src/hooks/` for custom React hooks
+- Avoid large files (>200 lines) - split into smaller modules
+- Prefer direct imports over barrel exports (index.ts files)
+
+## Testing
+
+```bash
+# Run unit tests
+pnpm test
+
+# Run tests with coverage
+pnpm test:coverage
+
+# Run E2E tests
+pnpm test:e2e
+
+# Type checking
+pnpm typecheck
+```
+
+## Development
+
+```bash
+# Start dev server
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Preview production build
+pnpm preview
+```
+
+## Important Rules
+
+1. **NEVER use `--no-verify` flag** when committing
+2. Always fix Biome issues before committing
+3. Keep functional programming patterns where possible
+4. Avoid `any` types - use proper TypeScript types
+5. Test async operations thoroughly
+6. Use `crypto.randomUUID()` for ID generation, not `Math.random()`

apps/playground/biome.json

@@ -9,10 +9,12 @@
     "ignoreUnknown": false,
     "includes": [
       "**/src/**/*",
+      "**/e2e/**/*",
       "**/.vscode/**/*",
       "**/index.html",
       "**/vite.config.js",
       "**/package.json",
+      "**/tsconfig.json",
       "!**/src/routeTree.gen.ts",
       "!**/src/styles.css"
     ]

apps/playground/e2e/collaborative-editor.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from "@playwright/test";
+import { expect, test } from "@playwright/test";
 
 test.describe("Collaborative Text Editor", () => {
   test.beforeEach(async ({ page }) => {

apps/playground/e2e/home.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from "@playwright/test";
+import { expect, test } from "@playwright/test";
 
 test.describe("Home Page", () => {
   test("should load home page successfully", async ({ page }) => {
@@ -21,8 +21,13 @@ test.describe("Home Page", () => {
     // Check for Two-Panel Editor Demo card - it's not a heading, it's a generic element
     await expect(page.getByText("Two-Panel Editor Demo")).toBeVisible();
 
-    // Check for Collaborative Editor card - also not a heading
-    await expect(page.getByText("Collaborative Editor")).toBeVisible();
+    // Check for Collaborative Editor card - use exact match to avoid ambiguity with Online Collaborative Editor
+    await expect(
+      page.getByText("Collaborative Editor", { exact: true }),
+    ).toBeVisible();
+
+    // Check for Online Collaborative Editor card
+    await expect(page.getByText("Online Collaborative Editor")).toBeVisible();
   });
 
   test("should navigate to two-panel editor", async ({ page }) => {
@@ -56,4 +61,22 @@ test.describe("Home Page", () => {
       page.getByRole("heading", { name: /Collaborative Text Editor/i }),
     ).toBeVisible();
   });
+
+  test("should navigate to online collaborative editor", async ({ page }) => {
+    await page.goto("/");
+    await page.waitForLoadState("networkidle");
+
+    // Click on Online Collaborative Editor card
+    await page
+      .getByRole("link", {
+        name: /Online Collaborative Editor/i,
+      })
+      .click();
+
+    // Verify navigation
+    await expect(page).toHaveURL(/\/demo\/online-collab-editor/);
+    await expect(
+      page.getByRole("heading", { name: /Online Collaborative Editor/i }),
+    ).toBeVisible();
+  });
 });

apps/playground/e2e/two-panel-editor.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from "@playwright/test";
+import { expect, test } from "@playwright/test";
 
 test.describe("Two-Panel Text Editor", () => {
   test.beforeEach(async ({ page }) => {