1 files changed, 117 insertions, 0 deletions
diff --git a/WEBSOCKET_FORMAT.md b/WEBSOCKET_FORMAT.md
new file mode 100644
index 0000000..93eead2
--- /dev/null
+++ b/WEBSOCKET_FORMAT.md
@@ -0,0 +1,117 @@
+# WebSocket Data Format
+
+TimePlot's WebSocket source accepts UTF-8 text frames whose contents can be parsed into one of the supported payload shapes below.
+
+## Recommended payload
+
+Send one JSON object per message:
+
+```json
+{
+  "timestampMs": 1250,
+  "value": 0.482
+}
+```
+
+Fields:
+
+- `value` — required numeric sample value
+- `timestampMs` — optional numeric source timestamp in milliseconds
+
+If `timestampMs` is present, TimePlot uses it to preserve the source timing relationship and aligns it onto the app's plot timebase.
+If `timestampMs` is omitted, TimePlot stamps the sample at the current plot time when the message arrives.
+
+## Other accepted object keys
+
+TimePlot also accepts these alternate numeric field names:
+
+- value fields: `value`, `y`, `signal`, `data`
+- time fields: `timeMs`, `timestampMs`, `timestamp`, `t`
+
+Examples:
+
+```json
+{"y": 0.91, "t": 2040}
+```
+
+```json
+{"signal": -0.13, "timestamp": 9810}
+```
+
+## Arrays
+
+A single message may contain an array of supported payloads:
+
+```json
+[
+  {"timestampMs": 1000, "value": 0.2},
+  {"timestampMs": 1100, "value": 0.3},
+  {"timestampMs": 1200, "value": 0.5}
+]
+```
+
+This is useful for batching.
+
+## Bare numeric messages
+
+These also work, though JSON objects are preferred:
+
+```text
+0.418
+```
+
+or:
+
+```json
+42.5
+```
+
+These are treated as samples without an explicit timestamp.
+
+## Unsupported / ignored messages
+
+Messages are ignored if TimePlot cannot find a numeric sample value.
+Examples of ignored payloads:
+
+- empty strings
+- non-numeric strings
+- JSON objects without a numeric `value`-like field
+
+## Demo server compatibility
+
+The included demo server sends messages like:
+
+```json
+{
+  "timestampMs": 1870,
+  "value": 0.735812,
+  "sequence": 19,
+  "profile": "telemetry"
+}
+```
+
+Extra fields are safe. TimePlot ignores anything it does not need.
+
+## Running the demo server
+
+```bash
+bun run ws:demo
+```
+
+Environment options:
+
+- `PORT` — default `8080`
+- `TIMEPLOT_PROFILE` — `telemetry`, `chirp`, `steps`, or `burst`
+- `TIMEPLOT_INTERVAL_MS` — message interval in milliseconds
+
+Example:
+
+```bash
+PORT=8090 TIMEPLOT_PROFILE=chirp TIMEPLOT_INTERVAL_MS=50 bun run ws:demo
+```
+
+Then set a signal source type to `WebSocket` and point it at:
+
+```text
+ws://localhost:8090
+```