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

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.0",
   "description": "Scaffold a new Pulse application",
   "main": "dist/index.js",
   "bin": {
@@ -29,4 +29,4 @@
     "tsup": "^8.0.2",
     "typescript": "^5.0.0"
   }
-}
+}

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.3.0",
+    "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

@@ -73,25 +73,35 @@ 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.
-        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);
-        }
-
-        // Record loopback delay (measures local processing overhead)
-        const loopbackDelay = Date.now() - sendTs;
-        setLastDelay(loopbackDelay);
-        delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), loopbackDelay];
+        // 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);
     }, [broadcast, logEvent]);
 
     // Computed delay stats

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

@@ -207,10 +207,13 @@ 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.
+            // 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;

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

@@ -101,10 +101,12 @@ 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];
+            // 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);
         }, 1000);
 
         return () => clearInterval(interval);

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.0",
+        "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,172 @@
+import { useState, useEffect, useCallback } from 'react'
+import { Pulse } from '@sansavision/pulse-sdk'
+
+/**
+ * Pulse v0.4.0 — 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)
+ *
+ * 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 QueueMessage {
+    id: string
+    payload: string
+    timestamp: number
+    state: 'pending' | 'in_flight' | 'acked' | 'dead_lettered'
+}
+
+export default function App() {
+    const [connected, setConnected] = useState(false)
+    const [messages, setMessages] = useState<QueueMessage[]>([])
+    const [input, setInput] = useState('')
+    const [rtt, setRtt] = useState<number | null>(null)
+    const [conn, setConn] = useState<any>(null)
+
+    useEffect(() => {
+        const pulse = new Pulse({ apiKey: 'dev' })
+
+        pulse.connect('ws://localhost:4001').then((connection) => {
+            setConn(connection)
+            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))
+        })
+
+        return () => {
+            conn?.close()
+        }
+    }, [])
+
+    const publish = useCallback(async () => {
+        if (!conn || !input.trim()) return
+
+        const msg: QueueMessage = {
+            id: crypto.randomUUID(),
+            payload: input.trim(),
+            timestamp: Date.now(),
+            state: 'pending',
+        }
+
+        const stream = conn.stream('task-queue', { qos: 'durable' })
+        stream.send(new TextEncoder().encode(JSON.stringify(msg)))
+        setMessages((prev) => [...prev, msg])
+        setInput('')
+    }, [conn, input])
+
+    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])
+
+    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>}
+            </p>
+
+            <div style={{ display: 'flex', gap: 8, marginBottom: 24 }}>
+                <input
+                    value={input}
+                    onChange={(e) => setInput(e.target.value)}
+                    onKeyDown={(e) => e.key === 'Enter' && publish()}
+                    placeholder="Enter a task 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>
+
+            <h2>Messages ({messages.length})</h2>
+            <div style={{ display: 'flex', flexDirection: 'column', gap: 8 }}>
+                {messages.map((msg) => (
+                    <div
+                        key={msg.id}
+                        style={{
+                            padding: 16, borderRadius: 8,
+                            background: msg.state === 'acked' ? '#064e3b' : msg.state === 'dead_lettered' ? '#7f1d1d' : '#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()} ·{' '}
+                                <span style={{
+                                    color: msg.state === 'acked' ? '#4ade80' : msg.state === 'dead_lettered' ? '#f87171' : '#facc15'
+                                }}>
+                                    {msg.state}
+                                </span>
+                            </div>
+                        </div>
+                        {msg.state === 'pending' && (
+                            <button
+                                onClick={() => ackMessage(msg.id)}
+                                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' }}>Server Configuration</strong>
+                <pre style={{ marginTop: 8 }}>
+                    {`# Start Pulse with WAL queue persistence:
+PULSE_QUEUE_BACKEND=wal PULSE_QUEUE_WAL_DIR=./data pulse dev
+
+# Or with PostgreSQL:
+PULSE_QUEUE_BACKEND=postgres PULSE_QUEUE_POSTGRES_URL=postgres://... pulse dev
+
+# Or with Redis:
+PULSE_QUEUE_BACKEND=redis PULSE_QUEUE_REDIS_URL=redis://localhost:6379 pulse dev
+
+# Enable encryption at rest (any backend):
+PULSE_QUEUE_KEY=$(openssl rand -hex 32) pulse dev`}
+                </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.3.0",
+    "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

@@ -81,25 +81,36 @@ 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.
-        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);
-        }
+        // 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);
 
-        // Record loopback delay so telemetry metrics are visible
-        const loopbackDelay = Date.now() - sendTs;
-        setLastDelay(loopbackDelay);
-        delayHistoryRef.current = [...delayHistoryRef.current.slice(-29), loopbackDelay];
+        // 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);
     }, [broadcast, logEvent]);
 
     const handleQualityChange = useCallback((quality: typeof QUALITY_OPTIONS[0]) => {