@sansavision/create-pulse 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sansavision/create-pulse",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Scaffold a new Pulse application",
   "main": "dist/index.js",
   "bin": {
@@ -29,4 +29,4 @@
     "tsup": "^8.0.2",
     "typescript": "^5.0.0"
   }
-}
+}

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

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@sansavision/pulse-sdk": "0.3.0",
+    "@sansavision/pulse-sdk": "^0.4.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "lucide-react": "^0.412.0"
@@ -24,4 +24,4 @@
     "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,41 +73,22 @@ export default function App() {
         const msg = { action, time, ts: sendTs };
         broadcast(msg);
 
-        // Single-tab simulation: defer peerTime update by the measured relay
-        // round-trip so that drift is visible and realistic. In a real
-        // multi-tab setup the relay echo handler (handleSyncMessage) updates
-        // peerTime — but since the relay does not echo back to the sender,
-        // we simulate it here with the actual measured delay.
-        const simulatedDelay = delayHistoryRef.current.length > 0
-            ? delayHistoryRef.current[delayHistoryRef.current.length - 1]
-            : 4; // sensible default ~4ms first message
-
-        setTimeout(() => {
-            if (action === 'tick') {
-                setPeerTime(time);
-            } else if (action === 'play') {
-                setIsPlaying(true);
-                setPeerTime(time);
-            } else if (action === 'pause') {
-                setIsPlaying(false);
-                setPeerTime(time);
-            } else if (action === 'seek') {
-                setPeerTime(time);
-            }
-        }, simulatedDelay);
-
-        // Measure delay after the event loop processes the send
-        setTimeout(() => {
-            const delay = Date.now() - sendTs;
-            setLastDelay(delay);
-            delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), delay];
-        }, 0);
+        // 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') {
+            setIsPlaying(true);
+            setPeerTime(time);
+        } else if (action === 'pause') {
+            setIsPlaying(false);
+            setPeerTime(time);
+        } else if (action === 'seek') {
+            setPeerTime(time);
+        }
     }, [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">
@@ -315,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>
@@ -364,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>
                 )}
 
@@ -379,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>
                 )}
 
@@ -394,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;
@@ -208,12 +229,6 @@ export function GameSync({ useChannel, logEvent }: GameSyncProps) {
             broadcast(payload);
 
             // Delay is measured in handleSyncMessage when the relay echoes back.
-            // Also measure locally via deferred setTimeout for single-tab demos.
-            setTimeout(() => {
-                const delay = Date.now() - sendTs;
-                setLastDelay(delay);
-                delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), delay];
-            }, 0);
 
             // Interpolate fallback for when broadcast doesn't echo locally fast enough
             const rv = remoteViewRef.current;
@@ -286,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,21 +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);
 
-            // Measure delay via deferred setTimeout for single-tab demos
-            setTimeout(() => {
-                const delay = Date.now() - sendTs;
-                setLastDelay(delay);
-                delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), delay];
-            }, 0);
+            // 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">
@@ -136,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/package.json

@@ -8,7 +8,7 @@
         "preview": "vite preview"
     },
     "dependencies": {
-        "@sansavision/pulse-sdk": "^0.4.0",
+        "@sansavision/pulse-sdk": "^0.4.1",
         "react": "^19.0.0",
         "react-dom": "^19.0.0"
     },

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

@@ -1,14 +1,16 @@
-import { useState, useEffect, useCallback } from 'react'
-import { Pulse } from '@sansavision/pulse-sdk'
+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.0 — Durable Queue Demo
+ * Pulse v0.4.4 — Durable Queue Demo
  *
  * This template demonstrates the persistent message queue system with:
- * - Publisher → Queue → Consumer flow over PLP
- * - At-least-once delivery semantics
- * - Dead-letter queue visibility
- * - Real-time metrics (RTT, packet loss)
+ * - 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)
@@ -17,66 +19,143 @@ import { Pulse } from '@sansavision/pulse-sdk'
  * - redis:    Redis (shared state / cache)
  */
 
-interface QueueMessage {
-    id: string
-    payload: string
-    timestamp: number
-    state: 'pending' | 'in_flight' | 'acked' | 'dead_lettered'
+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<QueueMessage[]>([])
+    const [messages, setMessages] = useState<DisplayMessage[]>([])
     const [input, setInput] = useState('')
     const [rtt, setRtt] = useState<number | null>(null)
-    const [conn, setConn] = useState<any>(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((connection) => {
-            setConn(connection)
+        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)
 
-            // Subscribe to queue stream
-            const stream = connection.stream('task-queue', { qos: 'durable' })
-            stream.on('data', (bytes: Uint8Array) => {
-                const msg = JSON.parse(new TextDecoder().decode(bytes))
-                setMessages((prev) => [...prev, msg])
-            })
-
             // Live metrics
-            connection.on('metrics', (m: any) => setRtt(m.rtt))
+            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 () => {
-            conn?.close()
+            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 () => {
-        if (!conn || !input.trim()) return
+        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])
 
-        const msg: QueueMessage = {
-            id: crypto.randomUUID(),
-            payload: input.trim(),
-            timestamp: Date.now(),
-            state: 'pending',
+    // 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 stream = conn.stream('task-queue', { qos: 'durable' })
-        stream.send(new TextEncoder().encode(JSON.stringify(msg)))
-        setMessages((prev) => [...prev, msg])
-        setInput('')
-    }, [conn, input])
+    const handleTtlChange = (value: string) => {
+        if (value === 'custom') {
+            setShowCustomTtl(true)
+        } else {
+            setShowCustomTtl(false)
+            setTtlSecs(value === '' ? undefined : parseInt(value, 10))
+        }
+    }
 
-    const ackMessage = useCallback(async (id: string) => {
-        if (!conn) return
-        await conn.service('queue', 'ack', { queue: 'task-queue', message_id: id })
-        setMessages((prev) =>
-            prev.map((m) => (m.id === id ? { ...m, state: 'acked' as const } : m))
-        )
-    }, [conn])
+    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 }}>
@@ -89,14 +168,18 @@ export default function App() {
                     <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>
 
-            <div style={{ display: 'flex', gap: 8, marginBottom: 24 }}>
+            {/* 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 task message..."
+                    placeholder="Enter a message..."
                     style={{
                         flex: 1, padding: '10px 16px', borderRadius: 8,
                         border: '1px solid #333', background: '#1a1a2e', color: '#fff', fontSize: 14
@@ -114,23 +197,74 @@ export default function App() {
                 </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.id}
+                        key={msg.sequence}
                         style={{
                             padding: 16, borderRadius: 8,
-                            background: msg.state === 'acked' ? '#064e3b' : msg.state === 'dead_lettered' ? '#7f1d1d' : '#1e1b4b',
+                            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 }}>
-                                {msg.id.slice(0, 8)} · {new Date(msg.timestamp).toLocaleTimeString()} ·{' '}
+                                seq:{msg.sequence} · deliveries:{msg.delivery_count} ·{' '}
                                 <span style={{
-                                    color: msg.state === 'acked' ? '#4ade80' : msg.state === 'dead_lettered' ? '#f87171' : '#facc15'
+                                    color: msg.state === 'acked' ? '#4ade80' : '#facc15'
                                 }}>
                                     {msg.state}
                                 </span>
@@ -138,7 +272,7 @@ export default function App() {
                         </div>
                         {msg.state === 'pending' && (
                             <button
-                                onClick={() => ackMessage(msg.id)}
+                                onClick={() => ackMessage(msg.sequence)}
                                 style={{
                                     padding: '6px 12px', borderRadius: 6, border: 'none',
                                     background: '#22c55e', color: '#000', fontWeight: 600, cursor: 'pointer'
@@ -152,19 +286,31 @@ export default function App() {
             </div>
 
             <div style={{ marginTop: 32, padding: 16, borderRadius: 8, background: '#111827', fontSize: 13, color: '#9ca3af' }}>
-                <strong style={{ color: '#e5e7eb' }}>Server Configuration</strong>
+                <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 }}>
-                    {`# Start Pulse with WAL queue persistence:
-PULSE_QUEUE_BACKEND=wal PULSE_QUEUE_WAL_DIR=./data pulse dev
+                    {`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')
 
-# Or with PostgreSQL:
-PULSE_QUEUE_BACKEND=postgres PULSE_QUEUE_POSTGRES_URL=postgres://... pulse dev
+// Publish with TTL
+await queue.publish('hello world', { ttlSecs: 60 })
 
-# Or with Redis:
-PULSE_QUEUE_BACKEND=redis PULSE_QUEUE_REDIS_URL=redis://localhost:6379 pulse dev
+// Pull + Ack
+const msg = await queue.pull()
+if (msg) await queue.ack(msg.sequence)
 
-# Enable encryption at rest (any backend):
-PULSE_QUEUE_KEY=$(openssl rand -hex 32) pulse dev`}
+// Drain all pending (useful after reconnect)
+const recovered = await queue.drain()`}
                 </pre>
             </div>
         </div>

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

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@sansavision/pulse-sdk": "0.3.0",
+    "@sansavision/pulse-sdk": "^0.4.1",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "lucide-react": "^0.412.0"
@@ -24,4 +24,4 @@
     "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,36 +81,19 @@ export default function App() {
         const msg = { action, time, ts: sendTs };
         broadcast(msg);
 
-        // Single-tab simulation: defer peerTime update by the measured relay
-        // round-trip so that drift is visible and realistic. In a real
-        // multi-tab setup the relay echo handler (handleSyncMessage) updates
-        // peerTime — but since the relay does not echo back to the sender,
-        // we simulate it here with the actual measured delay.
-        const simulatedDelay = delayHistoryRef.current.length > 0
-            ? delayHistoryRef.current[delayHistoryRef.current.length - 1]
-            : 4; // sensible default ~4ms first message
-
-        setTimeout(() => {
-            if (action === 'tick') {
-                setPeerTime(time);
-            } else if (action === 'play') {
-                setIsPlaying(true);
-                setPeerTime(time);
-            } else if (action === 'pause') {
-                setIsPlaying(false);
-                setPeerTime(time);
-            } else if (action === 'seek') {
-                setPeerTime(time);
-            }
-        }, simulatedDelay);
-
-        // Measure delay after the event loop processes the send (captures
-        // real serialization + WebSocket write time, not synchronous 0).
-        setTimeout(() => {
-            const delay = Date.now() - sendTs;
-            setLastDelay(delay);
-            delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), delay];
-        }, 0);
+        // 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') {
+            setIsPlaying(true);
+            setPeerTime(time);
+        } else if (action === 'pause') {
+            setIsPlaying(false);
+            setPeerTime(time);
+        } else if (action === 'seek') {
+            setPeerTime(time);
+        }
     }, [broadcast, logEvent]);
 
     const handleQualityChange = useCallback((quality: typeof QUALITY_OPTIONS[0]) => {
@@ -120,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';
 
@@ -193,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)}
@@ -262,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>