coaia-visualizer 1.4.3 → 1.5.0

package/.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+.next
+.git
+.env.local
+.env*.local
+test-results
+*.log
+.DS_Store

package/Dockerfile.app

@@ -0,0 +1,50 @@
+# Build stage
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json pnpm-lock.yaml ./
+
+# Install pnpm and dependencies
+RUN npm install -g pnpm@latest && \
+  pnpm install --frozen-lockfile
+
+# Copy application code
+COPY . .
+
+# Build Next.js application
+RUN pnpm build
+
+# Production stage
+FROM node:20-alpine AS runner
+
+WORKDIR /app
+
+# Install pnpm
+RUN npm install -g pnpm@latest
+
+# Copy package files
+COPY package.json pnpm-lock.yaml ./
+
+# Install production dependencies only, skip prepare hook
+RUN pnpm install --prod --frozen-lockfile --ignore-scripts
+
+# Copy built application from builder
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/next.config.mjs ./
+COPY --from=builder /app/app ./app
+COPY --from=builder /app/components ./components
+COPY --from=builder /app/lib ./lib
+COPY --from=builder /app/dist ./dist
+
+# Create data directories
+RUN mkdir -p /app/samples /app/test-data
+
+ENV NODE_ENV=production
+ENV PORT=4321
+
+EXPOSE 4321
+
+CMD ["pnpm", "start"]

package/Dockerfile.test

@@ -0,0 +1,24 @@
+FROM node:20-alpine
+
+WORKDIR /test
+
+# Install system dependencies
+RUN apk add --no-cache \
+  curl \
+  jq \
+  bash \
+  git \
+  python3 \
+  py3-pip
+
+# Create directories
+RUN mkdir -p /test-scripts /test-results /test-data
+
+# Copy test scripts
+COPY test-scripts /test-scripts
+
+# Make scripts executable
+RUN chmod +x /test-scripts/*.sh
+
+# Default command
+CMD ["/bin/bash"]

package/LIVE_MODE_DESIGN.md

@@ -0,0 +1,435 @@
+# 🎬 COAIA Visualizer: Live Narrative Observer Mode
+
+## Vision
+
+Transform coaia-visualizer into a **real-time narrative observatory** that watches structural tension charts being created, displays them as they emerge, and creates an immersive audio-visual experience.
+
+## Current State
+
+- ✅ Next.js app with JSONL parsing
+- ✅ Narrative beat display components
+- ✅ Manual reload button
+- ✅ Chart editing capabilities
+- ✅ CLI launcher with memory-path flag
+
+## Target State
+
+- 🎯 Live monitoring mode with auto-refresh
+- 🎯 Audio file integration with auto-play
+- 🎯 Timeline visualization
+- 🎯 Real-time beat appearance animations
+- 🎯 Observer dashboard for multiple sessions
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────┐
+│  Session: Creating Narrative Beats               │
+│  ├─ stc_observer.sh --read                       │
+│  │  ├─ Watches: _claude_PreToolUse.jsonl         │
+│  │  ├─ Processes: MCP tool calls                 │
+│  │  ├─ Generates: audio/{timestamp}.mp3/.txt     │
+│  │  └─ Appends: charts_*.coaia-narrative.jsonl   │
+│  └─ Outputs to: workspace/.coaia/*.jsonl         │
+└──────────────────────────────────────────────────┘
+                ↓ (polling every 2s)
+┌──────────────────────────────────────────────────┐
+│  coaia-visualizer --live                         │
+│  ├─ Polls JSONL for changes                      │
+│  ├─ Detects new beats (via beatCount)            │
+│  ├─ Auto-scrolls to latest                       │
+│  ├─ Plays audio/{timestamp}.mp3 (auto-play)      │
+│  ├─ Shows timeline with act progression          │
+│  └─ Live indicator (pulse animation)             │
+└──────────────────────────────────────────────────┘
+```
+
+## Implementation Plan
+
+### Phase 1: Live Monitoring Core
+
+#### 1.1. CLI Enhancement
+**File:** `cli.ts`
+
+```typescript
+// New flags
+--live                         Enable live monitoring mode
+--poll-interval MS             Polling interval (default: 2000ms)
+--auto-play                    Auto-play audio for new beats
+--audio-dir PATH               Audio directory (default: ./audio)
+```
+
+**Environment Variables:**
+```bash
+COAIAV_LIVE=true
+COAIAV_POLL_INTERVAL=2000
+COAIAV_AUTO_PLAY=true
+COAIAV_AUDIO_DIR=./audio
+```
+
+#### 1.2. Watch API Route
+**File:** `app/api/watch/route.ts`
+
+```typescript
+export async function GET() {
+  const memoryPath = process.env.COAIAV_MEMORY_PATH;
+  const stats = await fs.stat(memoryPath);
+  const content = await fs.readFile(memoryPath, 'utf-8');
+  const lines = content.trim().split('\n');
+
+  // Count beats
+  const beatCount = lines.filter(line => {
+    const record = JSON.parse(line);
+    return record.type === 'entity' &&
+           record.metadata?.type === 'narrative_beat';
+  }).length;
+
+  return NextResponse.json({
+    lastModified: stats.mtime.getTime(),
+    beatCount,
+    fileSize: stats.size
+  });
+}
+```
+
+#### 1.3. Audio API Route
+**File:** `app/api/audio/[timestamp]/route.ts`
+
+```typescript
+export async function GET(
+  request: NextRequest,
+  { params }: { params: { timestamp: string } }
+) {
+  const audioDir = process.env.COAIAV_AUDIO_DIR || './audio';
+  const audioPath = path.join(audioDir, `${params.timestamp}.mp3`);
+
+  const file = await fs.readFile(audioPath);
+  return new NextResponse(file, {
+    headers: {
+      'Content-Type': 'audio/mpeg',
+      'Content-Length': file.length.toString()
+    }
+  });
+}
+```
+
+### Phase 2: Live Mode UI
+
+#### 2.1. Live Monitor Hook
+**File:** `hooks/use-live-monitor.ts`
+
+```typescript
+export function useLiveMonitor(options: {
+  enabled: boolean;
+  pollInterval: number;
+  onNewBeat: (beat: EntityRecord) => void;
+}) {
+  const [lastBeatCount, setLastBeatCount] = useState(0);
+  const [isLive, setIsLive] = useState(false);
+
+  useEffect(() => {
+    if (!options.enabled) return;
+
+    const interval = setInterval(async () => {
+      const response = await fetch('/api/watch');
+      const { beatCount } = await response.json();
+
+      if (beatCount > lastBeatCount) {
+        setIsLive(true);
+        // Trigger reload and notify about new beats
+        const newBeatsCount = beatCount - lastBeatCount;
+        // Reload data and call onNewBeat for each new beat
+        setLastBeatCount(beatCount);
+      }
+    }, options.pollInterval);
+
+    return () => clearInterval(interval);
+  }, [options.enabled, options.pollInterval, lastBeatCount]);
+
+  return { isLive };
+}
+```
+
+#### 2.2. Audio Player Component
+**File:** `components/audio-player.tsx`
+
+```typescript
+export function AudioPlayer({
+  audioFiles,
+  autoPlay = false,
+  currentBeatIndex
+}: AudioPlayerProps) {
+  const audioRef = useRef<HTMLAudioElement>(null);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTrack, setCurrentTrack] = useState(0);
+
+  useEffect(() => {
+    if (autoPlay && audioRef.current && currentTrack < audioFiles.length) {
+      audioRef.current.play();
+    }
+  }, [currentTrack, autoPlay]);
+
+  return (
+    <div className="audio-player">
+      <audio
+        ref={audioRef}
+        src={`/api/audio/${audioFiles[currentTrack]}`}
+        onEnded={() => setCurrentTrack(prev => prev + 1)}
+        onPlay={() => setIsPlaying(true)}
+        onPause={() => setIsPlaying(false)}
+      />
+      {/* Playback controls */}
+    </div>
+  );
+}
+```
+
+#### 2.3. Timeline Component
+**File:** `components/narrative-timeline.tsx`
+
+```typescript
+export function NarrativeTimeline({ beats }: { beats: EntityRecord[] }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    // Auto-scroll to latest beat
+    if (containerRef.current) {
+      containerRef.current.scrollTop = containerRef.current.scrollHeight;
+    }
+  }, [beats.length]);
+
+  return (
+    <div ref={containerRef} className="timeline-container">
+      {beats.map((beat, idx) => (
+        <TimelineBeat
+          key={beat.name}
+          beat={beat}
+          index={idx}
+          isLatest={idx === beats.length - 1}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+#### 2.4. Live Indicator
+**File:** `components/live-indicator.tsx`
+
+```typescript
+export function LiveIndicator({ isLive }: { isLive: boolean }) {
+  return (
+    <div className="flex items-center gap-2">
+      <div className={`w-2 h-2 rounded-full ${
+        isLive ? 'bg-red-500 animate-pulse' : 'bg-gray-400'
+      }`} />
+      <span className="text-sm font-medium">
+        {isLive ? 'LIVE' : 'OFFLINE'}
+      </span>
+    </div>
+  );
+}
+```
+
+### Phase 3: Enhanced Page Component
+
+#### 3.1. Live Mode Page
+**File:** `app/live/page.tsx`
+
+```typescript
+"use client"
+
+export default function LivePage() {
+  const [beats, setBeats] = useState<EntityRecord[]>([]);
+  const [audioQueue, setAudioQueue] = useState<string[]>([]);
+  const isLiveMode = process.env.NEXT_PUBLIC_LIVE_MODE === 'true';
+  const pollInterval = parseInt(process.env.NEXT_PUBLIC_POLL_INTERVAL || '2000');
+
+  const { isLive } = useLiveMonitor({
+    enabled: isLiveMode,
+    pollInterval,
+    onNewBeat: (beat) => {
+      setBeats(prev => [...prev, beat]);
+      // Extract audio timestamp from beat metadata
+      const timestamp = beat.metadata.timestamp;
+      if (timestamp) {
+        setAudioQueue(prev => [...prev, timestamp]);
+      }
+    }
+  });
+
+  return (
+    <div className="min-h-screen bg-background">
+      <header className="border-b sticky top-0 z-10 bg-card">
+        <div className="container mx-auto px-4 py-4">
+          <div className="flex items-center justify-between">
+            <h1 className="text-2xl font-bold">
+              🎬 Live Narrative Observer
+            </h1>
+            <LiveIndicator isLive={isLive} />
+          </div>
+        </div>
+      </header>
+
+      <main className="container mx-auto px-4 py-8">
+        <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
+          {/* Timeline */}
+          <div className="lg:col-span-1">
+            <NarrativeTimeline beats={beats} />
+          </div>
+
+          {/* Beat Details */}
+          <div className="lg:col-span-2">
+            <NarrativeBeats beats={beats} />
+          </div>
+        </div>
+      </main>
+
+      {/* Audio Player */}
+      <AudioPlayer
+        audioFiles={audioQueue}
+        autoPlay={true}
+        currentBeatIndex={beats.length - 1}
+      />
+    </div>
+  );
+}
+```
+
+## Usage Examples
+
+### Example 1: Basic Live Mode
+```bash
+# Terminal 1: Start observer with audio
+cd /a/src/_sessiondata/55158baa-dea7-45c8-9941-540433cfe551
+./scripts/stc_observer.sh --read
+
+# Terminal 2: Start visualizer in live mode
+cd /src/coaia-visualizer
+npx coaia-visualizer --live \
+  --memory-path /home/mia/workspace/stcmastery-copilot-acp-55158baa-dea7-45c8-9941-540433cfe551--2602072108/.coaia/stcmastery-copilot-acp-55158baa-dea7-45c8-9941-540433cfe551--2602072108.jsonl \
+  --audio-dir /a/src/_sessiondata/55158baa-dea7-45c8-9941-540433cfe551/audio \
+  --auto-play
+```
+
+### Example 2: With Environment Variables
+```bash
+export COAIAV_LIVE=true
+export COAIAV_POLL_INTERVAL=3000
+export COAIAV_AUTO_PLAY=true
+export COAIAN_MF=/home/mia/workspace/stcmastery-copilot-acp-55158baa-dea7-45c8-9941-540433cfe551--2602072108/.coaia/stcmastery-copilot-acp-55158baa-dea7-45c8-9941-540433cfe551--2602072108.jsonl
+export COAIAV_AUDIO_DIR=/a/src/_sessiondata/55158baa-dea7-45c8-9941-540433cfe551/audio
+
+npx coaia-visualizer
+```
+
+### Example 3: Launch Script
+**File:** `/src/coaia-visualizer/launch-live.sh`
+
+```bash
+#!/bin/bash
+
+SESSION_ID="55158baa-dea7-45c8-9941-540433cfe551"
+SESSION_DIR="/a/src/_sessiondata/${SESSION_ID}"
+WORKSPACE_DIR="/home/mia/workspace/stcmastery-copilot-acp-${SESSION_ID}--2602072108"
+
+# Start observer in background
+cd "$SESSION_DIR"
+./scripts/stc_observer.sh --read &
+OBSERVER_PID=$!
+
+# Start visualizer in live mode
+cd /src/coaia-visualizer
+COAIAV_LIVE=true \
+COAIAV_AUTO_PLAY=true \
+COAIAN_MF="${WORKSPACE_DIR}/.coaia/stcmastery-copilot-acp-${SESSION_ID}--2602072108.jsonl" \
+COAIAV_AUDIO_DIR="${SESSION_DIR}/audio" \
+  npx coaia-visualizer
+
+# Cleanup
+kill $OBSERVER_PID
+```
+
+## Features Roadmap
+
+### Phase 1 (Core) ✨
+- [ ] File polling mechanism
+- [ ] Live mode flag in CLI
+- [ ] Auto-reload on JSONL changes
+- [ ] Audio player component
+- [ ] Auto-play integration
+
+### Phase 2 (Enhanced) 🎨
+- [ ] Timeline visualization
+- [ ] Beat appearance animations
+- [ ] Auto-scroll to latest
+- [ ] Live indicator with pulse
+- [ ] Playback controls
+
+### Phase 3 (Advanced) 🚀
+- [ ] Multi-session observer (watch multiple sessions)
+- [ ] WebSocket real-time updates (no polling)
+- [ ] Audio waveform visualization
+- [ ] Beat search/filter
+- [ ] Export timeline as video
+
+### Phase 4 (Immersive) 🌌
+- [ ] 3D narrative space visualization
+- [ ] VR/AR mode for narrative exploration
+- [ ] Collaborative real-time viewing
+- [ ] AI-generated beat summaries
+- [ ] Narrative pattern recognition
+
+## Technical Considerations
+
+### Performance
+- Polling every 2s is acceptable for local files
+- Consider debouncing rapid consecutive changes
+- Lazy-load audio files (stream, don't buffer all)
+
+### Audio Synchronization
+- Queue management: FIFO for auto-play
+- Handle concurrent audio generation
+- Graceful degradation if audio missing
+
+### State Management
+- Use React Context for live mode state
+- Local storage for user preferences (volume, auto-play)
+- Session storage for current playback position
+
+### Accessibility
+- Keyboard controls for audio (space = play/pause)
+- Screen reader announcements for new beats
+- Visual indicators for audio playback state
+
+## Integration Points
+
+### With stc_observer.sh
+- Observer writes to JSONL
+- Generates timestamped audio files
+- Visualizer reads both sources
+
+### With coaia-narrative MCP
+- Shared JSONL format
+- Compatible with existing tools
+- Can edit via visualizer, view via MCP
+
+### With Session Management
+- Multiple session directories
+- Session selector in UI
+- Parallel session monitoring
+
+## Error Handling
+
+- JSONL parse errors → Show error banner, keep previous state
+- Audio file not found → Silent skip, visual indicator
+- Network/file system errors → Retry with exponential backoff
+- Malformed beat data → Log, skip, continue
+
+## Success Metrics
+
+- ✅ Zero manual reloads needed
+- ✅ Audio plays within 3s of beat creation
+- ✅ Smooth animations at 60fps
+- ✅ No memory leaks during extended monitoring
+- ✅ Intuitive UX for narrative flow comprehension