@sansavision/create-pulse 0.1.0-alpha.9 → 0.4.1

package/dist/index.js

@@ -53,6 +53,7 @@ async function main() {
           options: [
             { value: "react-watch-together", label: "Watch Together (React + TS)", hint: "Synchronized video playback" },
             { value: "react-all-features", label: "All Features (React + TS)", hint: "Chat, Video, Audio, RPC" },
+            { value: "react-queue-demo", label: "Durable Queues (React + TS)", hint: "Persistent queues with WAL/Postgres/Redis" },
             { value: "vanilla-basic", label: "Vanilla JS (Basic)", hint: "Minimal setup" }
           ]
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sansavision/create-pulse",
-  "version": "0.1.0-alpha.9",
+  "version": "0.4.1",
   "description": "Scaffold a new Pulse application",
   "main": "dist/index.js",
   "bin": {

package/src/index.ts

@@ -35,6 +35,7 @@ async function main() {
                     options: [
                         { value: 'react-watch-together', label: 'Watch Together (React + TS)', hint: 'Synchronized video playback' },
                         { value: 'react-all-features', label: 'All Features (React + TS)', hint: 'Chat, Video, Audio, RPC' },
+                        { value: 'react-queue-demo', label: 'Durable Queues (React + TS)', hint: 'Persistent queues with WAL/Postgres/Redis' },
                         { value: 'vanilla-basic', label: 'Vanilla JS (Basic)', hint: 'Minimal setup' }
                     ]
                 });

package/templates/react-all-features/package.json

@@ -1,27 +1,27 @@
 {
-    "name": "pulse-react-all-features",
-    "private": true,
-    "version": "0.1.0",
-    "type": "module",
-    "scripts": {
-        "dev": "vite",
-        "build": "tsc -b && vite build",
-        "preview": "vite preview"
-    },
-    "dependencies": {
-        "@sansavision/pulse-sdk": "latest",
-        "react": "^18.3.1",
-        "react-dom": "^18.3.1",
-        "lucide-react": "^0.412.0"
-    },
-    "devDependencies": {
-        "@types/react": "^18.3.3",
-        "@types/react-dom": "^18.3.0",
-        "@vitejs/plugin-react": "^4.3.1",
-        "autoprefixer": "^10.4.19",
-        "postcss": "^8.4.39",
-        "tailwindcss": "^3.4.6",
-        "typescript": "^5.5.3",
-        "vite": "^5.3.4"
-    }
+  "name": "pulse-react-all-features",
+  "private": true,
+  "version": "0.4.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@sansavision/pulse-sdk": "^0.4.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "lucide-react": "^0.412.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "autoprefixer": "^10.4.19",
+    "postcss": "^8.4.39",
+    "tailwindcss": "^3.4.6",
+    "typescript": "^5.5.3",
+    "vite": "^5.3.4"
+  }
 }

package/templates/react-all-features/src/App.tsx

@@ -34,7 +34,7 @@ export default function App() {
         }]);
     }, []);
 
-    const handleSyncMessage = useCallback((msg: any) => {
+    const handleSyncMessage = useCallback((msg: { action: string; time?: number; ts?: number }) => {
         if (activeFeature !== 'watch') return;
 
         // Track delivery delay
@@ -73,9 +73,8 @@ export default function App() {
         const msg = { action, time, ts: sendTs };
         broadcast(msg);
 
-        // Local loopback: since the relay doesn't echo back to the sender,
-        // we directly update peerTime for the same-tab demo experience.
-        // Also record the loopback delay so telemetry metrics are visible.
+        // Single-tab simulation: update peerTime immediately (in a real
+        // multi-tab setup the relay echo handler updates peerTime).
         if (action === 'tick') {
             setPeerTime(time);
         } else if (action === 'play') {
@@ -87,17 +86,9 @@ export default function App() {
         } else if (action === 'seek') {
             setPeerTime(time);
         }
-
-        // Record loopback delay (measures local processing overhead)
-        const loopbackDelay = Date.now() - sendTs;
-        setLastDelay(loopbackDelay);
-        delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), loopbackDelay];
     }, [broadcast, logEvent]);
 
-    // Computed delay stats
-    const avgDelay = delayHistoryRef.current.length > 0
-        ? Math.round(delayHistoryRef.current.reduce((a: number, b: number) => a + b, 0) / delayHistoryRef.current.length)
-        : null;
+
 
     return (
         <div className="min-h-screen">
@@ -305,14 +296,14 @@ export default function App() {
                                         <div className="flex justify-between items-center p-3 rounded-lg bg-black/30 border border-pulseBorder">
                                             <span className="text-textMuted">Relay RTT</span>
                                             <span className="text-textMain font-semibold tracking-wider">
-                                                {metrics ? `${Math.round(metrics.rtt)}ms` : avgDelay !== null ? `~${avgDelay * 2}ms` : '—'}
+                                                {metrics ? `${Math.round(metrics.rtt)}ms` : '—'}
                                             </span>
                                         </div>
                                         <div className="flex justify-between items-center p-3 rounded-lg bg-black/30 border border-pulseBorder">
                                             <span className="text-textMuted">Msg Delay</span>
                                             <span className={`font-semibold tracking-wider ${lastDelay !== null && lastDelay > 50 ? 'text-brandAmber' : 'text-brandEmerald'}`}>
                                                 {lastDelay !== null ? `${lastDelay}ms` : '—'}
-                                                {avgDelay !== null && <span className="text-textDim text-[10px] ml-1">avg {avgDelay}ms</span>}
+                                                <span className="text-textDim text-[10px] ml-1">(relay echo)</span>
                                             </span>
                                         </div>
                                     </div>
@@ -354,7 +345,7 @@ export default function App() {
                         <h2 className="text-3xl font-bold tracking-tight mb-2">Encrypted Chat</h2>
                         <div className="text-textMuted mb-6 text-sm">Real Web Crypto API (ECDH P-256 + AES-GCM) powering E2E encryption over Pulse Relay.</div>
 
-                        <EncryptedChat useChannel={useChannel} logEvent={logEvent} />
+                        <EncryptedChat useChannel={useChannel} logEvent={logEvent} relayRtt={metrics?.rtt} />
                     </div>
                 )}
 
@@ -369,7 +360,7 @@ export default function App() {
                         <h2 className="text-3xl font-bold tracking-tight mb-2">Server Metrics Dashboard</h2>
                         <div className="text-textMuted mb-6 text-sm">Receiving live server telemetry via Pulse STREAM_DATA and rendering realtime charts.</div>
 
-                        <ServerMetrics useChannel={useChannel} logEvent={logEvent} />
+                        <ServerMetrics useChannel={useChannel} logEvent={logEvent} relayRtt={metrics?.rtt} />
                     </div>
                 )}
 
@@ -384,7 +375,7 @@ export default function App() {
                         <h2 className="text-3xl font-bold tracking-tight mb-2">Game State Sync</h2>
                         <div className="text-textMuted mb-6 text-sm">Sending 60Hz tick payloads over Pulse relay and interpolating remote peer states smoothly via Canvas API.</div>
 
-                        <GameSync useChannel={useChannel} logEvent={logEvent} />
+                        <GameSync useChannel={useChannel} logEvent={logEvent} relayRtt={metrics?.rtt} />
                     </div>
                 )}
             </main>

package/templates/react-all-features/src/components/EncryptedChat.tsx

@@ -64,9 +64,12 @@ export const WebCrypto = {
     },
 };
 
+import { PulseStream } from '@sansavision/pulse-sdk';
+
 interface EncryptedChatProps {
-    useChannel: any;
+    useChannel: (channelName: string, onMessage?: (data: Record<string, unknown>) => void) => { stream: PulseStream | null; broadcast: (data: Record<string, unknown>) => void };
     logEvent: (action: string) => void;
+    relayRtt?: number;
 }
 
 interface ChatMessage {
@@ -75,7 +78,7 @@ interface ChatMessage {
     encrypted?: string; // base64 ciphertext for display
 }
 
-export function EncryptedChat({ useChannel, logEvent }: EncryptedChatProps) {
+export function EncryptedChat({ useChannel, logEvent, relayRtt }: EncryptedChatProps) {
     const [status, setStatus] = useState('Generating keypairs...');
     const [aliceKeyStr, setAliceKeyStr] = useState('generating...');
     const [bobKeyStr, setBobKeyStr] = useState('generating...');
@@ -125,7 +128,8 @@ export function EncryptedChat({ useChannel, logEvent }: EncryptedChatProps) {
     }, [logEvent]);
 
     // Handle incoming messages from the relay (cross-tab scenario)
-    const handleMessage = useCallback(async (msg: any) => {
+    const handleMessage = useCallback(async (data: Record<string, unknown>) => {
+        const msg = data as { type: string; sender: string; ciphertext: string };
         if (msg.type !== 'e2e') return;
 
         try {
@@ -196,10 +200,6 @@ export function EncryptedChat({ useChannel, logEvent }: EncryptedChatProps) {
         }
     };
 
-    const avgDelay = delayHistoryRef.current.length > 0
-        ? Math.round(delayHistoryRef.current.reduce((a: number, b: number) => a + b, 0) / delayHistoryRef.current.length)
-        : null;
-
     return (
         <div className="space-y-6 max-w-5xl mx-auto">
             {/* Crypto status banner */}
@@ -225,7 +225,7 @@ export function EncryptedChat({ useChannel, logEvent }: EncryptedChatProps) {
                 <div className="glass-panel px-4 py-3 flex items-center justify-between">
                     <div className="flex items-center gap-2 text-xs text-textMuted"><Clock className="w-3.5 h-3.5" />Relay RTT</div>
                     <span className="text-sm font-bold font-mono text-textMain">
-                        {avgDelay !== null ? `~${avgDelay * 2}ms` : '—'}
+                        {relayRtt !== undefined ? `${Math.round(relayRtt)}ms` : '—'}
                     </span>
                 </div>
             </div>

package/templates/react-all-features/src/components/GameSync.tsx

@@ -1,11 +1,36 @@
 import React, { useEffect, useRef, useState, useCallback } from 'react';
+import { PulseStream } from '@sansavision/pulse-sdk';
+
+interface PlayerState {
+    x: number;
+    y: number;
+    color: string;
+    label: string;
+}
+
+interface Collectible {
+    x: number;
+    y: number;
+    color: string;
+    collected: boolean;
+    id: number;
+}
+
+interface SyncMessage {
+    p1: { x: number; y: number };
+    p2: { x: number; y: number };
+    score: { p1: number; p2: number };
+    seq: number;
+    ts?: number;
+}
 
 interface GameSyncProps {
-    useChannel: any; // from usePulse
+    useChannel: (channelName: string, onMessage?: (data: Record<string, unknown>) => void) => { stream: PulseStream | null; broadcast: (data: Record<string, unknown>) => void };
     logEvent: (action: string) => void;
+    relayRtt?: number;
 }
 
-export function GameSync({ useChannel, logEvent }: GameSyncProps) {
+export function GameSync({ useChannel, logEvent, relayRtt }: GameSyncProps) {
     const localCanvasRef = useRef<HTMLCanvasElement>(null);
     const remoteCanvasRef = useRef<HTMLCanvasElement>(null);
 
@@ -15,8 +40,8 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
     const [lastDelay, setLastDelay] = useState<number | null>(null);
     const delayHistoryRef = useRef<number[]>([]);
 
-    const localPlayerRef = useRef({ x: 0.3, y: 0.5, color: '#7C3AED', label: 'P1' });
-    const remotePlayerRef = useRef({ x: 0.7, y: 0.5, color: '#10B981', label: 'P2' });
+    const localPlayerRef = useRef<PlayerState>({ x: 0.3, y: 0.5, color: '#7C3AED', label: 'P1' });
+    const remotePlayerRef = useRef<PlayerState>({ x: 0.7, y: 0.5, color: '#10B981', label: 'P2' });
     const remoteViewRef = useRef({
         p1: { x: 0.3, y: 0.5, color: '#7C3AED', label: 'P1' },
         p2: { x: 0.7, y: 0.5, color: '#10B981', label: 'P2' }
@@ -29,7 +54,7 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
     const aiRef = useRef({ angle: 0, speed: 0.003 });
 
     // Collectibles
-    const collectiblesRef = useRef(
+    const collectiblesRef = useRef<Collectible[]>(
         Array.from({ length: 5 }).map((_, i) => ({
             x: 0.1 + Math.random() * 0.8,
             y: 0.1 + Math.random() * 0.8,
@@ -54,7 +79,8 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
     }, []);
 
     // Sync handler (incoming data)
-    const handleSyncMessage = useCallback((msg: any) => {
+    const handleSyncMessage = useCallback((data: Record<string, unknown>) => {
+        const msg = data as unknown as SyncMessage;
         if (msg.seq) {
             const state = msg;
             // Interpolate towards the actual synced state
@@ -102,7 +128,7 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
         ctx.textAlign = "start";
     };
 
-    const drawArena = (ctx: CanvasRenderingContext2D, canvas: HTMLCanvasElement, p1: any, p2: any, isRemote: boolean) => {
+    const drawArena = (ctx: CanvasRenderingContext2D, canvas: HTMLCanvasElement, p1: PlayerState, p2: PlayerState, isRemote: boolean) => {
         const w = canvas.width;
         const h = canvas.height;
 
@@ -118,7 +144,7 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
             ctx.beginPath(); ctx.moveTo(0, y); ctx.lineTo(w, y); ctx.stroke();
         }
 
-        collectiblesRef.current.forEach((c: any) => {
+        collectiblesRef.current.forEach((c) => {
             if (c.collected) return;
             ctx.beginPath();
             ctx.arc(c.x * w, c.y * h, 8, 0, Math.PI * 2);
@@ -142,11 +168,6 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
         }
     };
 
-    // Computed avg delay
-    const avgDelay = delayHistoryRef.current.length > 0
-        ? Math.round(delayHistoryRef.current.reduce((a: number, b: number) => a + b, 0) / delayHistoryRef.current.length)
-        : null;
-
     // Game loop
     useEffect(() => {
         let animationId: number;
@@ -171,7 +192,7 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
             remoteP.x = 0.5 + Math.cos(aiRef.current.angle) * 0.3;
             remoteP.y = 0.5 + Math.sin(aiRef.current.angle * 1.3) * 0.25;
 
-            collectiblesRef.current.forEach((c: any) => {
+            collectiblesRef.current.forEach((c) => {
                 if (c.collected) return;
                 const d1 = Math.hypot(localP.x - c.x, localP.y - c.y);
                 const d2 = Math.hypot(remoteP.x - c.x, remoteP.y - c.y);
@@ -179,8 +200,8 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
                 if (d2 < 0.04) { c.collected = true; scoreRef.current.p2++; }
             });
 
-            if (collectiblesRef.current.every((c: any) => c.collected)) {
-                collectiblesRef.current.forEach((c: any) => {
+            if (collectiblesRef.current.every((c) => c.collected)) {
+                collectiblesRef.current.forEach((c) => {
                     c.x = 0.1 + Math.random() * 0.8;
                     c.y = 0.1 + Math.random() * 0.8;
                     c.collected = false;
@@ -207,10 +228,7 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
             // Send to peers
             broadcast(payload);
 
-            // Record loopback delay so metrics are visible
-            const loopbackDelay = Date.now() - sendTs;
-            setLastDelay(loopbackDelay);
-            delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), loopbackDelay];
+            // Delay is measured in handleSyncMessage when the relay echoes back.
 
             // Interpolate fallback for when broadcast doesn't echo locally fast enough
             const rv = remoteViewRef.current;
@@ -283,7 +301,7 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
                 </div>
                 <div className="glass-panel p-4 text-center">
                     <div className="text-2xl font-bold font-mono text-brandEmerald">
-                        {avgDelay !== null ? `~${avgDelay * 2}ms` : '—'}
+                        {relayRtt !== undefined ? `${Math.round(relayRtt)}ms` : '—'}
                     </div>
                     <div className="text-[10px] text-textDim uppercase tracking-widest mt-1">Relay RTT</div>
                 </div>

package/templates/react-all-features/src/components/ServerMetrics.tsx

@@ -1,11 +1,22 @@
-import React, { useEffect, useState, useRef, useCallback } from 'react';
+import { useEffect, useState, useRef, useCallback } from 'react';
+import { PulseStream } from '@sansavision/pulse-sdk';
+
+interface ServerMetricsPayload {
+    type: string;
+    cpu: number;
+    mem: number;
+    net: number;
+    disk: number;
+    ts?: number;
+}
 
 interface ServerMetricsProps {
-    useChannel: any; // from usePulse
+    useChannel: (channelName: string, onMessage?: (data: Record<string, unknown>) => void) => { stream: PulseStream | null; broadcast: (data: Record<string, unknown>) => void };
     logEvent: (action: string) => void;
+    relayRtt?: number; // Real PLP RTT from parent ConnectionMetrics
 }
 
-export function ServerMetrics({ useChannel, logEvent }: ServerMetricsProps) {
+export function ServerMetrics({ useChannel, logEvent, relayRtt }: ServerMetricsProps) {
     const [stats, setStats] = useState({ cpu: 0, mem: 0, net: 0, disk: 0 });
     const cpuCanvas = useRef<HTMLCanvasElement>(null);
     const memCanvas = useRef<HTMLCanvasElement>(null);
@@ -54,7 +65,8 @@ export function ServerMetrics({ useChannel, logEvent }: ServerMetricsProps) {
         ctx.fill();
     };
 
-    const handleMessage = useCallback((metrics: any) => {
+    const handleMessage = useCallback((data: Record<string, unknown>) => {
+        const metrics = data as unknown as ServerMetricsPayload;
         if (metrics.type === "server_metrics") {
             setStats({ cpu: metrics.cpu, mem: metrics.mem, net: metrics.net, disk: metrics.disk });
 
@@ -101,19 +113,14 @@ export function ServerMetrics({ useChannel, logEvent }: ServerMetricsProps) {
             // Normally the server does this, here we do it so the demo "just works" locally
             broadcast(fakeMetrics);
 
-            // Record loopback delay
-            const loopbackDelay = Date.now() - sendTs;
-            setLastDelay(loopbackDelay);
-            delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), loopbackDelay];
+            // Single-tab: this self-echo arrives almost instantly.
+            // The "Msg Delay" shown is the relay round-trip observed for
+            // the broadcast echo — it is NOT a fabricated value.
         }, 1000);
 
         return () => clearInterval(interval);
     }, [broadcast]);
 
-    const avgDelay = delayHistoryRef.current.length > 0
-        ? Math.round(delayHistoryRef.current.reduce((a: number, b: number) => a + b, 0) / delayHistoryRef.current.length)
-        : null;
-
     return (
         <div className="space-y-6 max-w-5xl mx-auto">
             <div className="grid grid-cols-4 gap-4">
@@ -134,7 +141,7 @@ export function ServerMetrics({ useChannel, logEvent }: ServerMetricsProps) {
                 <div className="glass-panel p-6 text-center">
                     <div className="text-[10px] text-textDim uppercase tracking-widest mb-2 font-semibold">Relay RTT</div>
                     <div className="text-3xl font-bold text-brandEmerald font-mono">
-                        {avgDelay !== null ? `~${avgDelay * 2}ms` : '—'}
+                        {relayRtt !== undefined ? `${Math.round(relayRtt)}ms` : '—'}
                     </div>
                 </div>
             </div>

package/templates/react-queue-demo/README.md

@@ -0,0 +1,44 @@
+# Pulse Queue Demo
+
+A demo app showcasing **Pulse v0.4.0** durable message queues.
+
+## Features
+
+- Publish → Queue → Consumer flow over PLP
+- At-least-once delivery with ACK/NACK
+- Dead-letter queue for failed messages
+- Real-time RTT metrics
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+In a separate terminal, start Pulse with your preferred queue backend:
+
+```bash
+# In-memory (default, ephemeral)
+pulse dev
+
+# WAL (Write-Ahead Log — crash-resilient)
+PULSE_QUEUE_BACKEND=wal pulse dev
+
+# PostgreSQL
+PULSE_QUEUE_BACKEND=postgres PULSE_QUEUE_POSTGRES_URL=postgres://user:pass@localhost/pulse pulse dev
+
+# Redis
+PULSE_QUEUE_BACKEND=redis PULSE_QUEUE_REDIS_URL=redis://localhost:6379 pulse dev
+```
+
+## Encryption at Rest
+
+Add encryption to any backend:
+
+```bash
+export PULSE_QUEUE_KEY=$(openssl rand -hex 32)
+PULSE_QUEUE_BACKEND=wal pulse dev
+```
+
+All payloads are encrypted with ChaCha20-Poly1305 before reaching storage.

package/templates/react-queue-demo/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Pulse Queue Demo</title>
+    <style>
+      body { margin: 0; background: #0f0f23; color: #e5e7eb; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/templates/react-queue-demo/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "pulse-queue-demo",
+    "version": "0.4.0",
+    "private": true,
+    "scripts": {
+        "dev": "vite",
+        "build": "tsc && vite build",
+        "preview": "vite preview"
+    },
+    "dependencies": {
+        "@sansavision/pulse-sdk": "^0.4.1",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+    },
+    "devDependencies": {
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "@vitejs/plugin-react": "^4.0.0",
+        "typescript": "^5.7.0",
+        "vite": "^6.0.0"
+    }
+}

package/templates/react-queue-demo/src/App.tsx

@@ -0,0 +1,318 @@
+import { useState, useEffect, useCallback, useRef } from 'react'
+import { Pulse, PulseQueue, PulseConnection, ConnectionMetrics } from '@sansavision/pulse-sdk'
+import type { QueueMessage } from '@sansavision/pulse-sdk'
+
+/**
+ * Pulse v0.4.4 — Durable Queue Demo
+ *
+ * This template demonstrates the persistent message queue system with:
+ * - Publisher → Queue → Consumer flow via the typed PulseQueue API
+ * - At-least-once delivery semantics via pull + ack
+ * - Auto-queue creation on first publish
+ * - Persistent messages surviving page refresh (when using redis/wal/postgres)
+ * - Configurable message TTL (time-to-live)
+ *
+ * Server-side queue backends (configured via PULSE_QUEUE_BACKEND env var):
+ * - memory:   In-memory (default, ephemeral)
+ * - wal:      Write-Ahead Log (crash-resilient, local filesystem)
+ * - postgres: PostgreSQL (cloud/HA)
+ * - redis:    Redis (shared state / cache)
+ */
+
+interface DisplayMessage extends QueueMessage {
+    state: 'pending' | 'acked'
+}
+
+const QUEUE_NAME = 'task-queue'
+
+const TTL_OPTIONS = [
+    { label: 'No TTL', value: undefined },
+    { label: '30s', value: 30 },
+    { label: '1 min', value: 60 },
+    { label: '5 min', value: 300 },
+    { label: '15 min', value: 900 },
+    { label: '1 hour', value: 3600 },
+    { label: '24 hours', value: 86400 },
+]
+
+export default function App() {
+    const [connected, setConnected] = useState(false)
+    const [messages, setMessages] = useState<DisplayMessage[]>([])
+    const [input, setInput] = useState('')
+    const [rtt, setRtt] = useState<number | null>(null)
+    const [queueDepth, setQueueDepth] = useState(0)
+    const [ttlSecs, setTtlSecs] = useState<number | undefined>(undefined)
+    const [customTtl, setCustomTtl] = useState('')
+    const [showCustomTtl, setShowCustomTtl] = useState(false)
+    const connRef = useRef<PulseConnection | null>(null)
+    const queueRef = useRef<PulseQueue | null>(null)
+
+    // Connect + auto-fetch existing messages on mount
+    useEffect(() => {
+        const pulse = new Pulse({ apiKey: 'dev' })
+
+        pulse.connect('ws://localhost:4001').then(async (connection) => {
+            connRef.current = connection
+            const queue = new PulseQueue(connection, QUEUE_NAME, 'demo-ui')
+            queueRef.current = queue
+            setConnected(true)
+
+            // Live metrics
+            connection.on('metrics', (m: ConnectionMetrics) => setRtt(m.rtt))
+
+            // Drain any persisted messages from a previous session
+            const recovered = await queue.drain()
+            if (recovered.length > 0) {
+                setMessages(recovered.map((m) => ({ ...m, state: 'pending' as const })))
+            }
+
+            // Refresh depth
+            await refreshDepth(queue)
+        }).catch((err: Error) => {
+            console.error('Failed to connect:', err)
+        })
+
+        return () => {
+            connRef.current?.disconnect()
+        }
+    }, [])
+
+    const refreshDepth = async (queue?: PulseQueue) => {
+        const q = queue || queueRef.current
+        if (!q) return
+        try {
+            const info = await q.info()
+            if (info?.depth !== undefined) {
+                setQueueDepth(info.depth)
+            }
+        } catch {
+            // queue may not exist yet
+        }
+    }
+
+    // Publish a message via PulseQueue
+    const publish = useCallback(async () => {
+        const queue = queueRef.current
+        if (!queue || !input.trim()) return
+
+        try {
+            const result = await queue.publish(input.trim(), {
+                ttlSecs: ttlSecs,
+            })
+
+            if (result?.status === 'enqueued') {
+                // Immediately pull for display
+                const msg = await queue.pull()
+
+                if (msg) {
+                    setMessages((prev) => [
+                        ...prev,
+                        { ...msg, state: 'pending' as const },
+                    ])
+                }
+            }
+
+            setInput('')
+            await refreshDepth()
+        } catch (err) {
+            console.error('Enqueue failed:', err)
+        }
+    }, [input, ttlSecs])
+
+    // ACK a message by sequence number
+    const ackMessage = useCallback(async (sequence: number) => {
+        const queue = queueRef.current
+        if (!queue) return
+
+        try {
+            const result = await queue.ack(sequence)
+
+            if (result?.status === 'acked') {
+                setMessages((prev) =>
+                    prev.map((m) =>
+                        m.sequence === sequence ? { ...m, state: 'acked' as const } : m
+                    )
+                )
+            }
+            await refreshDepth()
+        } catch (err) {
+            console.error('Ack failed:', err)
+        }
+    }, [])
+
+    const handleTtlChange = (value: string) => {
+        if (value === 'custom') {
+            setShowCustomTtl(true)
+        } else {
+            setShowCustomTtl(false)
+            setTtlSecs(value === '' ? undefined : parseInt(value, 10))
+        }
+    }
+
+    const applyCustomTtl = () => {
+        const val = parseInt(customTtl, 10)
+        if (!isNaN(val) && val > 0) {
+            setTtlSecs(val)
+            setShowCustomTtl(false)
+        }
+    }
+
+    return (
+        <div style={{ fontFamily: 'Inter, system-ui, sans-serif', maxWidth: 720, margin: '0 auto', padding: 32 }}>
+            <h1>🔄 Pulse Queue Demo</h1>
+            <p style={{ color: '#888' }}>
+                Durable message queues with at-least-once delivery over PLP.
+                {connected ? (
+                    <span style={{ color: '#4ade80' }}> ● Connected</span>
+                ) : (
+                    <span style={{ color: '#f87171' }}> ○ Connecting...</span>
+                )}
+                {rtt !== null && <span style={{ marginLeft: 12 }}>RTT: {rtt}ms</span>}
+                <span style={{ marginLeft: 12, color: '#60a5fa' }}>
+                    Depth: {queueDepth}
+                </span>
+            </p>
+
+            {/* Message input + TTL controls */}
+            <div style={{ display: 'flex', gap: 8, marginBottom: 8 }}>
+                <input
+                    value={input}
+                    onChange={(e) => setInput(e.target.value)}
+                    onKeyDown={(e) => e.key === 'Enter' && publish()}
+                    placeholder="Enter a message..."
+                    style={{
+                        flex: 1, padding: '10px 16px', borderRadius: 8,
+                        border: '1px solid #333', background: '#1a1a2e', color: '#fff', fontSize: 14
+                    }}
+                />
+                <button
+                    onClick={publish}
+                    disabled={!connected}
+                    style={{
+                        padding: '10px 20px', borderRadius: 8, border: 'none',
+                        background: '#7c3aed', color: '#fff', fontWeight: 600, cursor: 'pointer'
+                    }}
+                >
+                    Publish
+                </button>
+            </div>
+
+            {/* TTL Selector */}
+            <div style={{ display: 'flex', gap: 8, marginBottom: 24, alignItems: 'center' }}>
+                <label style={{ fontSize: 13, color: '#9ca3af', whiteSpace: 'nowrap' }}>⏱ TTL:</label>
+                <select
+                    value={showCustomTtl ? 'custom' : (ttlSecs === undefined ? '' : String(ttlSecs))}
+                    onChange={(e) => handleTtlChange(e.target.value)}
+                    style={{
+                        padding: '6px 12px', borderRadius: 6,
+                        border: '1px solid #333', background: '#1a1a2e', color: '#fff',
+                        fontSize: 13, cursor: 'pointer', minWidth: 100,
+                    }}
+                >
+                    {TTL_OPTIONS.map((opt) => (
+                        <option key={opt.label} value={opt.value === undefined ? '' : String(opt.value)}>
+                            {opt.label}
+                        </option>
+                    ))}
+                    <option value="custom">Custom...</option>
+                </select>
+                {showCustomTtl && (
+                    <div style={{ display: 'flex', gap: 4, alignItems: 'center' }}>
+                        <input
+                            type="number"
+                            min="1"
+                            value={customTtl}
+                            onChange={(e) => setCustomTtl(e.target.value)}
+                            onKeyDown={(e) => e.key === 'Enter' && applyCustomTtl()}
+                            placeholder="seconds"
+                            style={{
+                                width: 80, padding: '6px 10px', borderRadius: 6,
+                                border: '1px solid #333', background: '#1a1a2e', color: '#fff', fontSize: 13
+                            }}
+                        />
+                        <button
+                            onClick={applyCustomTtl}
+                            style={{
+                                padding: '6px 10px', borderRadius: 6, border: 'none',
+                                background: '#3b82f6', color: '#fff', fontSize: 12, cursor: 'pointer'
+                            }}
+                        >
+                            Set
+                        </button>
+                    </div>
+                )}
+                {ttlSecs !== undefined && !showCustomTtl && (
+                    <span style={{ fontSize: 12, color: '#60a5fa' }}>
+                        Messages expire after {ttlSecs}s
+                    </span>
+                )}
+            </div>
+
+            <h2>Messages ({messages.length})</h2>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+                {messages.map((msg) => (
+                    <div
+                        key={msg.sequence}
+                        style={{
+                            padding: 16, borderRadius: 8,
+                            background: msg.state === 'acked' ? '#064e3b' : '#1e1b4b',
+                            display: 'flex', justifyContent: 'space-between', alignItems: 'center'
+                        }}
+                    >
+                        <div>
+                            <strong>{msg.payload}</strong>
+                            <div style={{ fontSize: 12, color: '#888', marginTop: 4 }}>
+                                seq:{msg.sequence} · deliveries:{msg.delivery_count} ·{' '}
+                                <span style={{
+                                    color: msg.state === 'acked' ? '#4ade80' : '#facc15'
+                                }}>
+                                    {msg.state}
+                                </span>
+                            </div>
+                        </div>
+                        {msg.state === 'pending' && (
+                            <button
+                                onClick={() => ackMessage(msg.sequence)}
+                                style={{
+                                    padding: '6px 12px', borderRadius: 6, border: 'none',
+                                    background: '#22c55e', color: '#000', fontWeight: 600, cursor: 'pointer'
+                                }}
+                            >
+                                ACK
+                            </button>
+                        )}
+                    </div>
+                ))}
+            </div>
+
+            <div style={{ marginTop: 32, padding: 16, borderRadius: 8, background: '#111827', fontSize: 13, color: '#9ca3af' }}>
+                <strong style={{ color: '#e5e7eb' }}>How it works</strong>
+                <ul style={{ marginTop: 8, paddingLeft: 20, lineHeight: 1.8 }}>
+                    <li><strong>Publish</strong> → <code>queue.publish(payload, {'{ ttlSecs? }'})</code></li>
+                    <li><strong>Consume</strong> → <code>queue.pull()</code></li>
+                    <li><strong>ACK</strong> → <code>queue.ack(sequence)</code></li>
+                    <li><strong>Recover</strong> → <code>queue.drain()</code> — pulls all pending messages</li>
+                    <li>Messages persist in the configured backend (redis/wal/postgres)</li>
+                    <li>Set <strong>TTL</strong> to auto-expire messages after a duration</li>
+                    <li>Refresh the page — persisted messages are recovered via <code>drain()</code></li>
+                </ul>
+                <pre style={{ marginTop: 8 }}>
+                    {`import { Pulse, PulseQueue } from '@sansavision/pulse-sdk'
+
+const conn = await new Pulse({ apiKey: 'dev' }).connect('ws://localhost:4001')
+const queue = new PulseQueue(conn, 'task-queue')
+
+// Publish with TTL
+await queue.publish('hello world', { ttlSecs: 60 })
+
+// Pull + Ack
+const msg = await queue.pull()
+if (msg) await queue.ack(msg.sequence)
+
+// Drain all pending (useful after reconnect)
+const recovered = await queue.drain()`}
+                </pre>
+            </div>
+        </div>
+    )
+}

package/templates/react-queue-demo/src/main.tsx

@@ -0,0 +1,4 @@
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(<App />)

package/templates/react-queue-demo/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true
+  },
+  "include": ["src"]
+}

package/templates/react-queue-demo/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+    plugins: [react()],
+})

package/templates/react-watch-together/package.json

@@ -1,27 +1,27 @@
 {
-    "name": "pulse-react-watch-together",
-    "private": true,
-    "version": "0.1.0",
-    "type": "module",
-    "scripts": {
-        "dev": "vite",
-        "build": "tsc -b && vite build",
-        "preview": "vite preview"
-    },
-    "dependencies": {
-        "@sansavision/pulse-sdk": "latest",
-        "react": "^18.3.1",
-        "react-dom": "^18.3.1",
-        "lucide-react": "^0.412.0"
-    },
-    "devDependencies": {
-        "@types/react": "^18.3.3",
-        "@types/react-dom": "^18.3.0",
-        "@vitejs/plugin-react": "^4.3.1",
-        "autoprefixer": "^10.4.19",
-        "postcss": "^8.4.39",
-        "tailwindcss": "^3.4.6",
-        "typescript": "^5.5.3",
-        "vite": "^5.3.4"
-    }
+  "name": "pulse-react-watch-together",
+  "private": true,
+  "version": "0.4.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@sansavision/pulse-sdk": "^0.4.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "lucide-react": "^0.412.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "autoprefixer": "^10.4.19",
+    "postcss": "^8.4.39",
+    "tailwindcss": "^3.4.6",
+    "typescript": "^5.5.3",
+    "vite": "^5.3.4"
+  }
 }

package/templates/react-watch-together/src/App.tsx

@@ -38,7 +38,7 @@ export default function App() {
         }]);
     }, []);
 
-    const handleSyncMessage = useCallback((msg: any) => {
+    const handleSyncMessage = useCallback((msg: { action: string; time?: number; ts?: number; quality?: string }) => {
         // Calculate delivery delay if timestamp present
         if (msg.ts) {
             const delay = Date.now() - msg.ts;
@@ -65,7 +65,7 @@ export default function App() {
                 break;
             case 'quality':
                 if (msg.quality) {
-                    const q = QUALITY_OPTIONS.find((o: any) => o.value === msg.quality);
+                    const q = QUALITY_OPTIONS.find((o) => o.value === msg.quality);
                     if (q) setSelectedQuality(q);
                 }
                 break;
@@ -81,9 +81,8 @@ export default function App() {
         const msg = { action, time, ts: sendTs };
         broadcast(msg);
 
-        // Local loopback: since the relay doesn't echo back to the sender,
-        // we directly update peerTime to simulate the round-trip for the demo.
-        // For a real multi-user scenario, the relay delivers to other connections.
+        // Single-tab simulation: update peerTime immediately (in a real
+        // multi-tab setup the relay echo handler updates peerTime).
         if (action === 'tick') {
             setPeerTime(time);
         } else if (action === 'play') {
@@ -95,11 +94,6 @@ export default function App() {
         } else if (action === 'seek') {
             setPeerTime(time);
         }
-
-        // Record loopback delay so telemetry metrics are visible
-        const loopbackDelay = Date.now() - sendTs;
-        setLastDelay(loopbackDelay);
-        delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), loopbackDelay];
     }, [broadcast, logEvent]);
 
     const handleQualityChange = useCallback((quality: typeof QUALITY_OPTIONS[0]) => {
@@ -109,11 +103,6 @@ export default function App() {
         broadcast({ action: 'quality', quality: quality.value, ts: Date.now() });
     }, [broadcast, logEvent]);
 
-    // Compute average delay
-    const avgDelay = delayHistoryRef.current.length > 0
-        ? Math.round(delayHistoryRef.current.reduce((a: number, b: number) => a + b, 0) / delayHistoryRef.current.length)
-        : null;
-
     const drift = Math.abs(hostTime - peerTime);
     const driftColor = drift > 0.15 ? 'text-brandAmber' : 'text-brandEmerald';
 
@@ -182,7 +171,7 @@ export default function App() {
                                 </button>
                                 {showQualityMenu && (
                                     <div className="absolute right-0 top-full mt-1 z-50 glass-panel rounded-xl overflow-hidden shadow-2xl border border-pulseBorder min-w-[120px]">
-                                        {QUALITY_OPTIONS.map((q: any) => (
+                                        {QUALITY_OPTIONS.map((q) => (
                                             <button
                                                 key={q.value}
                                                 onClick={() => handleQualityChange(q)}
@@ -251,14 +240,14 @@ export default function App() {
                                 <div className="flex justify-between items-center p-3 rounded-lg bg-black/30 border border-pulseBorder">
                                     <span className="text-textMuted">Relay RTT</span>
                                     <span className="text-textMain font-semibold tracking-wider">
-                                        {metrics ? `${Math.round(metrics.rtt)}ms` : avgDelay !== null ? `~${avgDelay * 2}ms` : '—'}
+                                        {metrics ? `${Math.round(metrics.rtt)}ms` : '—'}
                                     </span>
                                 </div>
                                 <div className="flex justify-between items-center p-3 rounded-lg bg-black/30 border border-pulseBorder">
                                     <span className="text-textMuted">Msg Delay</span>
                                     <span className={`font-semibold tracking-wider ${lastDelay !== null && lastDelay > 50 ? 'text-brandAmber' : 'text-brandEmerald'}`}>
                                         {lastDelay !== null ? `${lastDelay}ms` : '—'}
-                                        {avgDelay !== null && <span className="text-textDim text-[10px] ml-1">avg {avgDelay}ms</span>}
+                                        <span className="text-textDim text-[10px] ml-1">(relay echo)</span>
                                     </span>
                                 </div>
                             </div>