Migration march 2026 streaming

Migration Guide: Streaming & Betting Integration (March 2026)

Last Updated: March 23, 2026
PRs: #1064 (Performance), #1065 (Betting Feed)

Overview

This guide covers breaking changes and migration steps for the March 2026 streaming and betting integration updates.

Breaking Changes

1. Betting Feed Authentication Required

Change: All internal betting endpoints now require authentication.

Impact: Unauthenticated requests to /api/internal/bet-sync/* will receive 401 Unauthorized.

Migration:

# Server .env - add betting feed token
BETTING_FEED_ACCESS_TOKEN=your-random-secret-token

# Generate token
openssl rand -base64 32

Client Code:

// Old (no auth)
const response = await fetch("/api/internal/bet-sync/state");

// New (Bearer header)
const response = await fetch("/api/internal/bet-sync/state", {
  headers: { Authorization: `Bearer ${BETTING_FEED_ACCESS_TOKEN}` },
});

// New (query param for EventSource)
const eventSource = new EventSource(
  `/api/internal/bet-sync/events?streamToken=${BETTING_FEED_ACCESS_TOKEN}`
);

2. CORS Restrictions on Internal Endpoints

Change: Internal betting endpoints restrict CORS to specific origin.

Impact: Cross-origin requests from non-allowed origins will receive CORS errors.

Migration:

# Server .env - set allowed origin
INTERNAL_BET_SYNC_ALLOWED_ORIGIN=https://your-betting-frontend.com

Server Response:

Access-Control-Allow-Origin: https://your-betting-frontend.com
Access-Control-Allow-Credentials: true

3. Embedded Client Origin Validation

Change: Embedded clients now validate postMessage origins against explicit allowlist.

Impact: HYPERSCAPE_AUTH messages from untrusted origins are rejected.

Migration:

# Client .env - set trusted embed origins
PUBLIC_EMBED_ALLOWED_ORIGINS=https://embed.example.com,https://partner.example.com

Client Code:

// Old (accepts from any origin)
window.addEventListener("message", (event) => {
  if (event.data?.type === "HYPERSCAPE_AUTH") {
    config.authToken = event.data.authToken;
  }
});

// New (validates origin)
import { isTrustedEmbedOrigin, parseHyperscapeAuthMessage } from "@/lib/embeddedAuth";

const trustedOrigins = resolveTrustedEmbedOrigins({
  currentOrigin: window.location.origin,
  publicAppUrl: import.meta.env.PUBLIC_APP_URL,
  embedAllowedOrigins: import.meta.env.PUBLIC_EMBED_ALLOWED_ORIGINS,
});

window.addEventListener("message", (event) => {
  if (!isTrustedEmbedOrigin(event.origin, trustedOrigins)) {
    console.warn("Ignoring message from untrusted origin:", event.origin);
    return;
  }
  
  const message = parseHyperscapeAuthMessage(event.data);
  if (message) {
    applyHyperscapeAuthMessage(config, message);
  }
});

4. Streaming Token in URL Hash (Not Query)

Change: Streaming tokens moved from query params to URL hash fragments.

Impact: Tokens in query params are deprecated and will be removed in future versions.

Migration:

// Old (query param - appears in server logs)
const url = `http://localhost:3333/stream?streamToken=${token}`;

// New (hash fragment - not sent to server)
const url = `http://localhost:3333/stream#streamToken=${token}`;

Client Code:

import { getStreamingAccessToken, primeStreamingAccessTokenFromWindow } from "@/lib/streamingAccessToken";

// Scrub token from URL before React mounts
primeStreamingAccessTokenFromWindow(window);

// Get cached token
const token = getStreamingAccessToken();

5. Vite 8 Polyfill Changes

Change: Removed vite-plugin-node-polyfills, manual Buffer injection required.

Impact: Solana and crypto libraries need manual Buffer global.

Migration:

// packages/client/src/polyfills/buffer-shim.ts
import { Buffer } from "buffer";

// Inject Buffer global for libraries that expect it
(globalThis as Record<string, unknown>).Buffer = Buffer;

export default Buffer;

Vite Config:

// vite.config.ts

// REMOVED
import { nodePolyfills } from "vite-plugin-node-polyfills";
plugins: [
  nodePolyfills({ include: ["buffer"], globals: { Buffer: true } }),
]

// ADDED
// Import buffer-shim.ts in your entry point
import "./polyfills/buffer-shim";

6. Manual Chunk Splitting Function

Change: Vite 8 (Rolldown) requires manualChunks as function, not object.

Impact: Build errors if using object-style manualChunks.

Migration:

// vite.config.ts

// Old (object - no longer works)
manualChunks: {
  "vendor-react": ["react", "react-dom"],
  "vendor-three": ["three"],
}

// New (function - required for Rolldown)
manualChunks(id: string) {
  if (id.includes("node_modules/react-dom") || id.includes("node_modules/react/")) {
    return "vendor-react";
  }
  if (id.includes("node_modules/three/")) {
    return "vendor-three";
  }
}

New Features

Renderer Health Monitoring

Client-Side Globals:

// Exposed for capture pipeline health probes
window.__HYPERSCAPE_STREAM_READY__: boolean
window.__HYPERSCAPE_STREAM_RENDERER_HEALTH__: {
  ready: boolean;
  degradedReason: string | null;
  updatedAt: number;
  phase: string | null;
}
window.__HYPERSCAPE_STREAM_BOOT_STATUS__: string | null

Usage:

// Check if stream is ready for capture
if (window.__HYPERSCAPE_STREAM_READY__) {
  startCapture();
}

// Check detailed health
const health = window.__HYPERSCAPE_STREAM_RENDERER_HEALTH__;
if (!health.ready) {
  console.warn(`Renderer degraded: ${health.degradedReason}`);
}

Streaming Guardrails

Shared Validation (packages/shared/src/utils/rendering/streamingGuardrails.ts):

import { deriveStreamingGuardrailReason } from "@hyperscape/shared";

const degradedReason = deriveStreamingGuardrailReason({
  phase: cycle.phase,
  agent1: { id: "a", name: "Agent A", hp: 10, maxHp: 10 },
  agent2: { id: "b", name: "Agent B", hp: 8, maxHp: 10 },
  arenaPositions: { agent1: [1, 0, 1], agent2: [4, 0, 4] },
});

if (degradedReason) {
  console.warn(`Streaming guardrail failed: ${degradedReason}`);
}

Validation Rules:

• Agents must have valid id, name, hp, maxHp
• hp must be in range [0, maxHp]
• Arena positions required for COUNTDOWN and FIGHTING phases
• Positions must not overlap (different tiles)

DuelBettingBridge

Lifecycle Management:

import { DuelBettingBridge } from "./DuelBettingBridge";

const bridge = new DuelBettingBridge(world, solanaOperator, config);

// Bridge listens to streaming events automatically
world.on("streaming:announcement", handleStreamingAnnouncement);
world.on("streaming:fight:start", handleStreamingFightStart);
world.on("streaming:resolution", handleStreamingResolution);
world.on("streaming:abort", handleStreamingAbort);

// Reconciliation loop runs every 1s
// Ensures market state stays aligned with streaming lifecycle

Configuration:

# Reconciliation interval (default: 1000ms)
DUEL_BETTING_RECONCILE_INTERVAL_MS=1000

# Market history size (default: 100)
DUEL_BETTING_MARKET_HISTORY_SIZE=100

Testing

Unit Tests

Betting Feed Auth:

npm test packages/server/src/routes/__tests__/streaming-betting-auth.test.ts

Betting Feed Payload:

npm test packages/server/src/routes/__tests__/streaming-betting-feed.test.ts

DuelBettingBridge:

npm test packages/server/src/systems/DuelScheduler/__tests__/DuelBettingBridge.test.ts

Streaming Guardrails:

npm test packages/shared/src/utils/rendering/__tests__/streamingGuardrails.test.ts

Integration Tests

StreamingMode Component:

npm test packages/client/tests/unit/screens/StreamingMode.component.test.tsx

Renderer Health Derivation:

npm test packages/client/tests/unit/screens/StreamingMode.test.ts

Manual Testing

1. Start Server:

bun run dev

2. Test Bootstrap Endpoint:

curl -H "Authorization: Bearer $BETTING_FEED_ACCESS_TOKEN" \
  http://localhost:5555/api/internal/bet-sync/state | jq

3. Test SSE Feed:

curl -H "Authorization: Bearer $BETTING_FEED_ACCESS_TOKEN" \
  http://localhost:5555/api/internal/bet-sync/events

4. Check Renderer Health:

# Open stream in browser
open http://localhost:3333/stream.html

# Check console
window.__HYPERSCAPE_STREAM_RENDERER_HEALTH__

Rollback

If you need to rollback to pre-March 2026 behavior:

1. Disable Betting Feed

# Server .env
BETTING_FEED_ACCESS_TOKEN=  # Leave empty to disable

2. Revert to Public Polling

// Use public spectator endpoint (no auth required)
const response = await fetch("http://localhost:5555/api/streaming/state");
const state = await response.json();

3. Disable Embedded Auth Validation

# Client .env
PUBLIC_EMBED_ALLOWED_ORIGINS=  # Leave empty to allow all origins (dev only)

Note: This is NOT recommended for production. Use explicit allowlist.

Support

• Issues: Report bugs in main Hyperscape repository
• Documentation: See docs/streaming-betting-integration.md for detailed guide
• API Reference: See docs/api-betting-feed.md for complete API documentation
• Hyperbet Integration: See HyperscapeAI/hyperbet#28 for consumer-side implementation