npm package: @sirendesign/markup
Description: A web markup and feedback tool for collecting visual feedback from clients and account managers
Latest version: 1.0.36

# @siren/markup

A powerful web markup and feedback tool for collecting visual feedback from clients and account managers. Similar to [marker.io](https://marker.io), this tool provides an easy-to-use widget for capturing screenshots, adding annotations, and managing feedback items.

## ✨ New: Firebase Integration

**Multi-tenant feedback with authentication and real-time sync!** See [FIREBASE_SETUP.md](./FIREBASE_SETUP.md) for complete setup instructions.

- 🔒 **User Authentication** - Email/password authentication via Firebase
- ☁️ **Cloud Storage** - Feedback stored in Firestore with real-time sync
- 🏢 **Multi-Tenancy** - Each website/project has isolated feedback
- 🔄 **Real-time Updates** - Changes sync instantly across all devices
- 👥 **User Tracking** - Know who submitted each ticket

## Features

- 📸 **Screenshot Capture** - Capture viewport screenshots with one click
- ✏️ **Annotation Tools** - Add arrows, rectangles, circles, highlights, text, and freehand drawings
- ✂️ **Copy Amendments** - Click on text to suggest changes with before/after comparison
- 📋 **Session Activity Timeline** - Records user interactions (clicks, navigation, scrolls, inputs) during the session
- 🎨 **Design Mockup Overlay** - Upload mockups and overlay them on the live site for pixel-perfect comparison
- 🔍 **Component Detection** - Automatically identifies React components and HTML elements
- 💬 **Feedback Management** - Create, view, and manage feedback items
- 🏷️ **Tags & Priority** - Organize feedback with custom tags and priority levels (Low, Medium, High, Critical)
- 📊 **Status Tracking** - Track feedback status (Open, In Progress, Resolved, Closed)
- 👥 **Role-Based Permissions** - Edit/Delete restricted to developers and feedback creators
- 💾 **Local or Cloud Storage** - Works offline or with Firebase sync
- 🔌 **API Integration** - Optional API endpoint for server-side storage
- ⌨️ **Keyboard Shortcuts** - Quick access with customizable shortcuts
- 🎨 **Customizable** - Theming, labels, and position options

## Installation

```bash
npm install @siren/markup firebase
# or
yarn add @siren/markup firebase
# or
pnpm add @siren/markup firebase
```

Note: `firebase` is included as a peer dependency if you want to use authentication and cloud sync.

## Quick Start

### Basic Setup (Local Storage)

```tsx
import { MarkupWidget } from '@siren/markup';
import '@siren/markup/dist/styles.css';

function App() {
  return (
    <div>
      <YourApp />
      
      <MarkupWidget
        config={{
          projectId: 'my-project',
          primaryColor: '#6366f1',
        }}
      />
    </div>
  );
}
```

### With Firebase (Authentication & Cloud Sync)

```tsx
import { MarkupWidget, initFirebase } from '@siren/markup';
import '@siren/markup/dist/styles.css';

// 1. Create .env in YOUR app (not the npm package):
//    VITE_FIREBASE_API_KEY=...
//    VITE_FIREBASE_AUTH_DOMAIN=...
//    etc.

// 2. YOUR app reads .env and calls initFirebase once
initFirebase({
  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
  storageBucket: import.meta.env.VITE_FIREBASE_STORAGE_BUCKET,
  messagingSenderId: import.meta.env.VITE_FIREBASE_MESSAGING_SENDER_ID,
  appId: import.meta.env.VITE_FIREBASE_APP_ID,
});

function App() {
  return (
    <div>
      <YourApp />
      
      <MarkupWidget config={{ projectId: 'my-website-prod' }} />
    </div>
  );
}
```

**With Firebase enabled:**
- ✅ Users must sign in to submit feedback
- ✅ Feedback syncs across devices in real-time
- ✅ Each `projectId` has isolated feedback
- ✅ Track who submitted each ticket

See [FIREBASE_SETUP.md](./FIREBASE_SETUP.md) for complete setup instructions.

### Next.js App Router

For Next.js 13+ with the App Router, create a client component:

```tsx
// components/FeedbackWidget.tsx
'use client';

import { MarkupWidget } from '@siren/markup';
import '@siren/markup/dist/styles.css';

export default function FeedbackWidget() {
  return (
    <MarkupWidget
      config={{
        projectId: 'my-project',
          id: 'user-123',
          name: 'John Doe',
          email: 'john@example.com',
        },
      }}
    />
  );
}
```

Then use it in your layout:

```tsx
// app/layout.tsx
import FeedbackWidget from '@/components/FeedbackWidget';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <FeedbackWidget />
      </body>
    </html>
  );
}
```

## Configuration Options

```typescript
interface MarkupConfig {
  // Required: Project identifier
  projectId: string;
  
  // User information (optional)
  user?: {
    id: string;
    name: string;
    email: string;
    avatar?: string;
    role?: 'admin' | 'developer' | 'client' | 'account-manager';
  };
  
  // API endpoint for storing feedback (uses local storage if not provided)
  apiEndpoint?: string;
  
  // API key for authentication
  apiKey?: string;
  
  // Widget position (default: 'bottom-right')
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  
  // Primary color (default: '#6366f1')
  primaryColor?: string;
  
  // Whether widget opens by default
  defaultOpen?: boolean;
  
  // Keyboard shortcut (default: 'ctrl+shift+m')
  shortcut?: string;
  
  // Custom labels
  labels?: {
    widgetButton?: string;
    feedbackTitle?: string;
    submitButton?: string;
    cancelButton?: string;
  };
  
  // Callback when feedback is submitted
  onSubmit?: (feedback: FeedbackItem) => void | Promise<void>;
  
  // Callback when status changes
  onStatusChange?: (feedbackId: string, status: FeedbackStatus) => void | Promise<void>;
  
  // Tags available for feedback
  availableTags?: string[];
  
  // Team members for assignment
  teamMembers?: UserInfo[];
}
```

## API Integration

To store feedback on your server, provide an `apiEndpoint`:

```tsx
<MarkupWidget
  config={{
    projectId: 'my-project',
    apiEndpoint: 'https://api.yourserver.com',
    apiKey: 'your-api-key',
    onSubmit: async (feedback) => {
      // Custom handling after submission
      console.log('Feedback submitted:', feedback);
    },
  }}
/>
```

### Expected API Endpoints

If you provide an `apiEndpoint`, implement these endpoints:

- `GET /projects/:projectId/feedback` - List all feedback
- `POST /projects/:projectId/feedback` - Create feedback
- `PATCH /projects/:projectId/feedback/:id` - Update feedback
- `DELETE /projects/:projectId/feedback/:id` - Delete feedback
- `POST /projects/:projectId/feedback/:id/comments` - Add comment
- `POST /projects/:projectId/upload` - Upload screenshot (returns `{ url: string }`)

## Using the Store Directly

Access the feedback store for custom integrations:

```tsx
import { useMarkupStore } from '@company/markup';

function AdminDashboard() {
  const { feedbackItems, updateFeedbackItem } = useMarkupStore();
  
  const openItems = feedbackItems.filter(item => item.status === 'open');
  
  return (
    <div>
      <h2>Open Feedback ({openItems.length})</h2>
      {openItems.map(item => (
        <div key={item.id}>
          <h3>{item.title}</h3>
          <button onClick={() => updateFeedbackItem(item.id, { status: 'in-progress' })}>
            Start Working
          </button>
        </div>
      ))}
    </div>
  );
}
```

## Customization

### Custom Styling

Override CSS variables for custom theming:

```css
.markup-widget {
  --markup-primary: #your-brand-color;
  --markup-primary-hover: #your-brand-color-darker;
  --markup-bg: #ffffff;
  --markup-bg-secondary: #f3f4f6;
  --markup-border: #e5e7eb;
  --markup-text: #1f2937;
  --markup-text-secondary: #6b7280;
  --markup-radius: 12px;
}
```

### Custom Labels

```tsx
<MarkupWidget
  config={{
    projectId: 'my-project',
    labels: {
      widgetButton: 'Report Issue',
      feedbackTitle: 'Submit Feedback',
      submitButton: 'Send',
      cancelButton: 'Close',
    },
  }}
/>
```

## Advanced Features

### Session Activity Timeline

The widget automatically tracks user interactions during their session, including:
- **Clicks** - Element details, text content, HTML structure
- **Navigation** - URL changes and page visits
- **Scrolling** - Scroll position changes
- **Input Events** - Form interactions (values are masked for privacy)

When viewing feedback, click "Play Session" to see a chronological timeline of these actions, helping developers understand the user's journey before reporting an issue.

### Design Mockup Overlay

Upload a design mockup image and overlay it on the live site to compare:
1. Click "Upload Design Mockup" when creating feedback
2. Select your design file (PNG, JPG, SVG)
3. View the feedback and toggle the overlay with opacity slider
4. Perfect for pixel-perfect QA and design review

### Component Detection

The tool automatically identifies:
- React component names (from `data-component` or React Fiber)
- HTML element structure (tag, id, classes)
- Text content of clicked elements

This information is attached to copy amendment feedback to help developers locate exact elements in code.

## Development

```bash
# Build the package
npm run build

# Watch mode for development
npm run dev

# Type check
npm run type-check

# Run tests
npm test

# Run tests with coverage
npm run test:coverage
```

## Testing

Comprehensive test suite for all environments:

```bash
# Run all tests
npm test

# Run specific test suites
npm run test:unit          # Unit tests
npm run test:integration   # PHP integration tests
npm run test:coverage      # With coverage report

# Test PHP environment locally
npm run test:php           # Starts PHP server on :8080

# Run all environment tests
./scripts/test-all.sh

# Pre-publish validation
./scripts/pre-publish.sh
```

See [TESTING.md](./TESTING.md) for detailed testing documentation.

### PHP Testing

A complete PHP test environment is included:

```bash
cd php-test
php -S localhost:8080
```

Then open http://localhost:8080 to test the widget in a PHP environment.

See [php-test/README.md](./php-test/README.md) for details.

## Production Deployment

Before deploying to production:

1. Run validation: `npm run validate`
2. Build: `npm run build`
3. Test all environments: `./scripts/test-all.sh`
4. Review: [PRODUCTION_CHECKLIST.md](./PRODUCTION_CHECKLIST.md)
5. Publish: `npm publish --access public`

See [PRODUCTION_CHECKLIST.md](./PRODUCTION_CHECKLIST.md) for the complete deployment checklist.

## CDN Usage

For non-React/PHP environments, use the standalone bundle:

```html
<!-- React Dependencies -->
<script crossorigin src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>

<!-- Markup Widget -->
<script src="https://cdn.jsdelivr.net/npm/@sirendesign/markup@latest/dist/markup-widget.js"></script>

<script>
  MarkupWidget.init({
    projectId: 'my-project',
    primaryColor: '#6366f1'
  });
</script>
```

See [CDN_SETUP.md](./CDN_SETUP.md) and [PHP_INTEGRATION.md](./PHP_INTEGRATION.md) for details.

## Documentation

- [CDN Setup Guide](./CDN_SETUP.md) - Deploy to CDN for PHP/non-React sites
- [PHP Integration](./PHP_INTEGRATION.md) - Using the widget in PHP applications
- [Firebase Setup](./FIRESTORE_SETUP.md) - Cloud storage and authentication
- [User Profiles](./USER_PROFILES.md) - User management and roles
- [Testing Guide](./TESTING.md) - Comprehensive testing documentation
- [Production Checklist](./PRODUCTION_CHECKLIST.md) - Pre-deployment validation

## License

MIT