@masuidrive/ticket

🎫 Real-time ticket tracking viewer for development workflow

A modern web-based ticket viewer that provides real-time updates for your markdown-based ticket system. Perfect for tracking development progress with live updates, mermaid diagrams, and HTML previews.

Features

• 📝 Markdown Ticket Support: View and track tickets written in markdown
• 🔄 Real-time Updates: Automatic refresh when ticket files change
• 📊 Mermaid Diagrams: Render flowcharts, sequence diagrams, and more
• 🌐 HTML Previews: Preview HTML content with iframe sandboxing
• 🎨 Dark/Light Theme: Automatic theme switching support
• ⚡ Fast Performance: Built with Vite for lightning-fast development
• 🔗 SSE Connection: Server-Sent Events for live updates
• 📑 Table of Contents: Collapsible TOC with smooth scrolling navigation
• 🔝 Scroll to Top: Quick return button for easy navigation
• 🗺️ Breadcrumb Navigation: Sticky header showing current section hierarchy
• 🖱️ Quick Navigation: Double-click anywhere to jump to table of contents

Quick Start

Run the ticket viewer in any directory:

npx @masuidrive/ticket

This will:

• Look for current-ticket.md in the current directory
• Start a web server at http://localhost:4932
• Open the ticket viewer in your browser

Usage

Basic Usage

# Start in current directory
npx @masuidrive/ticket

# Start in specific directory
npx @masuidrive/ticket ./my-project

# Start on custom port
npx @masuidrive/ticket -p 3000

# Combine options
npx @masuidrive/ticket -d ./my-project -p 3000

Command Line Options

Options:
  -p, --port <number>    Server port (default: 4932)
  -h, --host <address>   Server host address (default: localhost)
  -d, --dir <path>       Project directory containing current-ticket.md
  --help                 Show help message

Examples:
  npx @masuidrive/ticket                           # Current directory, localhost:4932
  npx @masuidrive/ticket ./my-project             # Specific directory
  npx @masuidrive/ticket -p 3000                  # Custom port
  npx @masuidrive/ticket -h 0.0.0.0               # Listen on all interfaces
  npx @masuidrive/ticket -h 0.0.0.0 -p 3000       # External access on port 3000
  npx @masuidrive/ticket -h 0.0.0.0 -p 3000 -d ./my-project  # Full options

Ticket Format

The viewer looks for current-ticket.md in your project directory. Here's an example ticket format:

---
priority: 1
tags: ["frontend", "bug"]
description: "Fix navigation component styling"
created_at: "2025-01-15T10:30:00Z"
started_at: "2025-01-15T11:00:00Z"
closed_at: null
---

# Fix Navigation Component Styling

## Overview
The navigation component has styling issues in dark mode...

## Tasks
- [x] Identify CSS issues
- [ ] Fix dark mode colors
- [ ] Test responsive design

## Mermaid Diagram
```mermaid
flowchart TD
    A[Identify Issue] --> B[Fix Styles]
    B --> C[Test Changes]
    C --> D[Deploy]
```

## HTML Preview
```html-preview
<div class="nav-component">
  <h1>Navigation Preview</h1>
  <nav>...</nav>
</div>
```

Features in Detail

Real-time Updates

The viewer automatically refreshes when your ticket files change, providing instant feedback as you update your tickets.

Mermaid Diagram Support

Render various diagram types:

• Flowcharts
• Sequence diagrams
• Class diagrams
• Gantt charts
• And more...

HTML Preview

Preview HTML content safely with iframe sandboxing. Perfect for mockups and UI previews.

Theme Support

Automatic dark/light theme switching based on system preferences, with manual toggle available.

Enhanced Navigation

• Table of Contents: Automatically generated from markdown headers (H1-H6) with collapsible interface
• Sticky Breadcrumb: Shows current section hierarchy at the top of the page as you scroll
• Scroll to Top: Floating button appears after scrolling 100px for quick return to top
• Quick Jump: Double-click on empty space anywhere on the page to jump to table of contents
• Header Return Links: Hover over any heading to see a "↑" button that returns to table of contents
• Japanese Support: Full Unicode support with URL-safe encoding for smooth scrolling

Requirements

• Node.js 18.0.0 or higher
• Modern web browser with ES2020 support

Development

If you want to contribute or run from source:

git clone https://github.com/masuidrive/ticket-sh-viewer.git
cd ticket-sh-viewer
npm install
npm run build
npm start

Architecture

• Frontend: Vite + React + TypeScript + Tailwind CSS
• Backend: Express.js with Server-Sent Events (SSE)
• Real-time: File watching with chokidar
• Diagrams: Mermaid.js integration
• Previews: Sandboxed iframe rendering

License

MIT License - see LICENSE file for details

Author

masuidrive

Repository

https://github.com/masuidrive/ticket-sh-viewer

Issues

Report issues at: https://github.com/masuidrive/ticket-sh-viewer/issues