---
name: STAGESHARE_THREAD
for: wellscope.stageshare/1.0.0
homepage: https://dx.horizontalwireline.ai/STAGESHARE_THREAD.md
---

# Stage Share thread — chat vs depth comments

Same route. Two row kinds. The guest overlay and the cabin must treat them the same.

Canonical: `GET https://dx.horizontalwireline.ai/STAGESHARE_THREAD.md`

Older units that always send `depth_ft` are posting **pins**, not chat. To post chat, omit `depth_ft`.

## Endpoint

```
POST /v1/stageshare/rooms/{id}/comments
Authorization: Bearer hwx_…   (operator / Pi)
           or: Bearer sst_…   (guest)
```

Aliases: `body` or `text`; `column_id` or `column`.

`GET …/comments` returns a **JSON array** (not `{ comments: [] }`). Skip rows with `deleted_at`.

WS: `{ "type": "comment", "payload": { …row, "op": "add"|"edit"|"delete" } }`

## Chat (thread message)

No measured depth. The guest sidebar shows **name · time · body** as a plain chat row. No plot pin.

```
{ "text": "Coming on depth" }
{ "body": "Coming on depth" }
```

- Omit `depth_ft` (or send `null`).
- Omit `column_id` / `column`.
- 201 `{ depth_ft: null, column_id: null, body, text, author, … }`.

Do **not** invent a depth of `0` or the current tool MD to “make the field required.” That becomes a pin at 0 ft.

## Depth comment (pin)

A note at a measured depth on a column. Guest shows a highlighted card with **`@8080.4 ft · LIVE`**. Click jumps the plot. A pin is drawn on **that column** (falls back to the depth axis if the column is collapsed).

When live is promoted, pins whose `depth_ft` sits in the promoted span move with the LAS (`column_id` becomes `rih` / `corr` / `pump` / `pooh` / `tally`). Chat stays chat. See [`/STAGESHARE_LOGS.md`](https://dx.horizontalwireline.ai/STAGESHARE_LOGS.md).

```
{ "depth_ft": 8080.4, "column_id": "live", "body": "Possible collar" }
{ "depth_ft": 8080.4, "column": "live", "text": "Possible collar" }
```

- `depth_ft` required and finite (`-100` … `40000`).
- `column_id` or `column`: `tally` | `live` | `rih` | `corr` | `pump` | `pooh`.
- 201 includes both `depth_ft` and `column_id` / `column`.

## How to tell them apart

| | Chat | Depth comment |
|--|------|----------------|
| `depth_ft` | `null` / omitted | number |
| `column_id` | `null` / omitted | one of the six columns |
| Guest thread | `.ss-cmt.is-chat` — name · time · body | `.ss-cmt.is-pin` + `@####.# ft` |
| Plot | none | pin on that column at `depth_ft`; click centers that depth |
| Cabin Copy / Pi | same POST, no depth | same POST, with depth + column |

`GET` is one list. Filter in the UI: `depth_ft == null` → chat; else → pin.

## Guest behaviour (DX)

- One sidebar. Chat composer at the bottom is **chat only** (no depth).
- Enter sends; Shift+Enter newline.
- Right-click the log → depth comment at that `depth_ft` + `column_id`.
- Both kinds appear in the same thread, visually separated.
- **Chat:** own rows align right, labeled **You**, gold fill. Everyone else aligns left in a muted bubble. Do not paint chat maroon.
- **Depth comments:** HWS maroon `#820024` **contour only** (no fill) on `.ss-cmt.is-pin` and the plot chips. Click jumps the plot to that MD.

## What not to do

- Do not POST this to `/v1/inbound`.
- Do not send `css_px`, `x`, or `y`.
- Do not require a depth on every comment. Chat is first-class.
- Do not bump `wellscope.stageshare` for this — 1.0.0 already allows omitted `depth_ft`.