From 7f795eac6afc092a9d46f7e85a20db05cb083ba0 Mon Sep 17 00:00:00 2001
From: enzotar <enzotar3000@gmail.com>
Date: Wed, 25 Feb 2026 14:37:16 -0800
Subject: [PATCH] docs: add compiler-native streaming syntax to language
 reference

- Added streaming (source/receiver) to status table
- Documented 'stream' declaration, 'stream from' expression
- Streaming modes table (signal/delta/pixel)
- CLI 'dreamstack stream' usage
---
 DREAMSTACK.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/DREAMSTACK.md b/DREAMSTACK.md
index 8c06231..d089327 100644
--- a/DREAMSTACK.md
+++ b/DREAMSTACK.md
@@ -33,6 +33,8 @@ DreamStack is **real and running** — 7 Rust crates, 39 tests, 9 examples, ~7KB
 | Layout | Cassowary constraint solver | ✅ |
 | Types | `Signal<Int>`, `Derived<Bool>` | ✅ Hindley-Milner |
 | Dev server | `dreamstack dev app.ds` | ✅ HMR |
+| Streaming (source) | `stream main on "ws://..."` | ✅ Signal diffs |
+| Streaming (receiver) | `stream from "ws://..."` | ✅ Auto-reconnect |
 | Router | `route "/path" -> body` / `navigate` | ✅ Hash-based |
 | Two-way binding | `input { bind: name }` | ✅ Signal ↔ input |
 | Async resources | `DS.resource()` / `DS.fetchJSON()` | ✅ Loading/Ok/Err |
@@ -464,6 +466,63 @@ open examples/stream-source.html    # source: renders + streams
 open examples/stream-receiver.html  # receiver: displays bytes
 ```
 
+### Compiler-Native Streaming
+
+The `stream` keyword makes any `.ds` app streamable with one line. The compiler generates all WebSocket connection, binary protocol encoding, and signal diff broadcasting automatically.
+
+#### Source: `stream` declaration
+
+```
+let count = 0
+let doubled = count * 2
+
+stream counter on "ws://localhost:9100" { mode: signal }
+
+view counter =
+  column [
+    text count
+    text doubled
+    button "+" { click: count += 1 }
+  ]
+```
+
+The compiler:
+1. Calls `DS._initStream(url, mode)` on load → connects to relay
+2. Wraps every signal mutation with `DS._streamDiff("count", count.value)` → sends JSON diff frames
+3. Sends scene body positions at 60fps when a physics scene is streaming
+
+#### Receiver: `stream from` expression
+
+```
+let remote = stream from "ws://localhost:9100"
+
+view main =
+  column [
+    text remote.count
+    text remote.doubled
+  ]
+```
+
+Compiles to `DS._connectStream(url)` — returns a reactive `Signal` that merges incoming `FRAME_SIGNAL_SYNC` and `FRAME_SIGNAL_DIFF` frames.
+
+#### Streaming Modes
+
+| Mode | Keyword | What's Sent | Bandwidth |
+|------|---------|-------------|----------|
+| Signal | `signal` (default) | JSON diffs of changed signals | ~2 KB/s |
+| Delta | `delta` | XOR + RLE compressed pixel deltas | ~50 KB/s |
+| Pixel | `pixel` | Raw RGBA framebuffer every frame | ~30 MB/s |
+
+#### CLI
+
+```bash
+# Compile and serve with streaming enabled
+dreamstack stream app.ds --relay ws://localhost:9100 --mode signal
+
+# Or explicitly declare streaming in the .ds file and use dev server
+dreamstack dev app.ds
+```
+
 ---
 
 ## Phase 8: Physics Scene — Rapier2D in the Language