bitcoin-inscription-viewer/README.md

🔍 A robust, production-ready React/TypeScript library for viewing Bitcoin Ordinals inscriptions with advanced optimization features including LRU caching, LaserEyes wallet integration, virtual scrolling, and performance monitoring

# 🔍 Bitcoin Inscription Viewer

A React/TypeScript library for displaying Bitcoin Ordinals inscriptions with responsive design and comprehensive content support.

**🔧 Compatibility:** React 18 & React 19 | TypeScript 5+ | Modern Browsers

## 🚀 Quick Start

```bash
npm install bitcoin-inscription-viewer
```

```jsx
import { InscriptionGallery } from 'bitcoin-inscription-viewer';

function MyApp() {
  const inscriptionIds = [
    '6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0',
    'e317a2a5d68bd1004ae15a06175a319272a10389ff125c98820389edef8b0a94i0'
  ];

  return (
    <InscriptionGallery
      inscriptionIds={inscriptionIds}
      columns={3}
      cardSize={200}
      enableModal={true}
    />
  );
}
```

## ✨ Features

- **🎨 Responsive Design** - Works perfectly in any container size
- **🖼️ Content Support** - Images, videos, audio, 3D models, JSON, text, HTML
- **💰 Wallet Integration** - Built-in LaserEyes wallet support
- **⚡ Performance** - Lazy loading, caching, and optimization features
- **🔧 Flexible** - Customizable layouts, themes, and behaviors
- **📱 Mobile-First** - Optimized for all screen sizes
- **🛡️ Type Safe** - Full TypeScript support

## 📖 Documentation

Visit our comprehensive documentation:

- **[🎮 Live React Demo](https://switch-900.github.io/InscriptionViewer/)** - Interactive React demo with all features
- **[📚 Complete Documentation](docs/index.html)** - Full integration guides and examples
- **[⚡ Integration Guide](INTEGRATION-GUIDE.html)** - Quick setup and patterns
- **[💰 LaserEyes Integration](LASEREYES-INTEGRATION.html)** - Wallet integration guide
- **[🎮 Legacy Examples](api-examples.html)** - Static HTML demos

## ⚠️ Important: Implementation Status (Updated Dec 2024)

**For Production Use:** Please refer to our **[Working Features Only](test-pages/working-features-only.html)** page for accurate implementation details.

Some of our examples show "aspirational" features that aren't fully implemented yet. We've now:

- ✅ **Fixed all runtime errors** - No more `toUpperCase()` crashes or unsafe operations
- ✅ **Added comprehensive error handling** - ErrorBoundary components throughout
- ✅ **Created working-only examples** - [Working Features Only](test-pages/working-features-only.html) for production reference
- ✅ **Added implementation status** - [Full status breakdown](IMPLEMENTATION-STATUS.md) explains what works vs. what's planned
- ✅ **Enhanced safety** - All string operations, array access, and user inputs properly validated

**Quick Reference:**
- **[📋 Implementation Status](IMPLEMENTATION-STATUS.md)** - What works vs. what's planned
- **[✅ Working Features Only](test-pages/working-features-only.html)** - Production examples
- **[🧪 All Test Pages](test-pages/index.html)** - Full test suite

## 🔧 Core Components

### InscriptionGallery
Display multiple inscriptions in a responsive grid:

```jsx
<InscriptionGallery
  inscriptionIds={['inscription1', 'inscription2']}
  columns={3}
  cardSize={200}
  enableModal={true}
  showIndex={true}
/>
```

### LaserEyesInscriptionGallery
Auto-fetch inscriptions from connected LaserEyes wallet:

```jsx
import { LaserEyesProvider } from '@omnisat/lasereyes';

<LaserEyesProvider>
  <LaserEyesInscriptionGallery
    columns={3}
    cardSize={250}
    enableModal={true}
  />
</LaserEyesProvider>
```

### InscriptionRenderer
Display individual inscriptions with full controls:

```jsx
<InscriptionRenderer
  inscriptionId="6fb976ab49dcec017f1e201e84395983204ae1a7c2abf7ced0a85d692e442799i0"
  size={400}
  showHeader={true}
  showControls={true}
/>
```

## 🎯 Use Cases

- **Wallet Applications** - Display user inscription collections
- **NFT Marketplaces** - Showcase inscriptions for sale
- **Portfolio Trackers** - Monitor inscription values
- **Explorer Tools** - Browse and analyze inscriptions
- **Collection Galleries** - Curate inscription displays

## ⚡ Advanced Features

- **Enhanced Caching** - LRU cache with TTL support
- **Batch Fetching** - Efficient concurrent loading
- **Virtual Scrolling** - Handle thousands of inscriptions
- **Performance Monitoring** - Real-time metrics
- **Service Worker** - Offline support and intelligent caching
- **Custom Fetchers** - Pluggable data sources

## 🛠️ Installation & Setup

### NPM
```bash
npm install bitcoin-inscription-viewer
```

### Yarn
```bash
yarn add bitcoin-inscription-viewer
```

### Import Styles
```jsx
import 'bitcoin-inscription-viewer/dist/style.css';
```

## 🌐 API Support

Works with any Bitcoin Ordinals API:
- **Recursive endpoints** (recommended) - No Bitcoin node required
- **Standard endpoints** - Fallback support
- **Custom servers** - Configure your own endpoints

## 🚀 Service Worker Caching

The library includes an optional service worker for intelligent caching and offline support. The service worker provides:

- **Smart Caching** - Automatic caching of inscription content and metadata
- **Offline Support** - View previously loaded inscriptions without internet
- **Performance** - Dramatically faster load times for cached content
- **Bandwidth Savings** - Reduce API calls and data usage

### In-Memory Caching

The library includes built-in in-memory caching for improved performance:

```jsx
import { useInscriptionCache } from 'bitcoin-inscription-viewer';

function App() {
  const { 
    cachedData,
    cacheSize,
    clearCache,
    getCachedData,
    setCachedData
  } = useInscriptionCache();

  return (
    <div>
      <div>Cache Size: {Object.keys(cachedData).length} entries</div>
      <button onClick={clearCache}>Clear Cache</button>
      {/* Your inscription components */}
    </div>
  );
}
```

### Caching Features

- **Automatic Caching** - Content is automatically cached after first load
- **LRU Eviction** - Least recently used items are removed when cache is full
- **Memory Efficient** - Configurable cache size limits
- **Manual Control** - Programmatic cache management
- **Performance Monitoring** - Cache hit/miss statistics

The caching system improves load times for frequently viewed inscriptions and reduces API requests.

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## 📄 License

MIT License - see LICENSE file for details.

## 🔗 Links

- **GitHub**: https://github.com/switch-900/InscriptionViewer
- **NPM**: https://www.npmjs.com/package/bitcoin-inscription-viewer
- **Documentation**: https://switch-900.github.io/InscriptionViewer

---

Built with ❤️ for the Bitcoin ecosystem