docs: update spectrum-ts documentation for v1.6.0 (#20)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: photon-action-bot[bot]

docs-src/spectrum-ts/content.mdx.vel

@@ -1,14 +1,14 @@
 ---
 title: "Content"
-description: "Build text, attachments, voice, contacts, polls, rich links, groups, and platform-specific content for outgoing messages"
+description: "Build text, attachments, voice, contacts, polls, rich links, groups, replies, edits, typing indicators, and platform-specific content for outgoing messages"
 ---
 
 import { TypeTooltip } from "/snippets/type-tooltip.mdx";
 
 {% set ci = symbol("ts:spectrum-ts#ContentInput") %}
 {% set cb = symbol("ts:spectrum-ts#ContentBuilder") %}
 
-Spectrum exposes a family of content builders — `text`, `attachment`, `voice`, `contact`, `richlink`, `poll`, `group`, and `custom` — plus a string shortcut that's equivalent to `text()`. Any API that takes a <TypeTooltip name="ContentInput" type={`{{ ci.signature }}`} /> accepts a plain string or a <TypeTooltip name="ContentBuilder" type={`{{ cb.signature }}`} />.
+Spectrum exposes a family of content builders — `text`, `attachment`, `voice`, `contact`, `richlink`, `poll`, `group`, `custom`, `reaction`, `reply`, `edit`, and `typing` — plus a string shortcut that's equivalent to `text()`. Any API that takes a <TypeTooltip name="ContentInput" type={`{{ ci.signature }}`} /> accepts a plain string or a <TypeTooltip name="ContentBuilder" type={`{{ cb.signature }}`} />.
 
 ## Text
 
@@ -200,7 +200,45 @@ import { custom } from "spectrum-ts";
 await space.send(custom({ type: "card", title: "Order Confirmed" }));
 ```
 
-The raw payload round-trips through the provider's `actions.send` — it's up to the provider to interpret it.
+The raw payload round-trips through the provider's `send` action — it's up to the provider to interpret it.
+
+## Replies
+
+Send a threaded reply by wrapping content with the message being replied to. See [Reactions and replies](/spectrum-ts/reactions-and-replies) for the full details and sugar methods.
+
+```ts
+import { reply, text } from "spectrum-ts";
+
+await space.send(reply(text("Got it"), message));
+```
+
+`reply()` cannot wrap `reply`, `edit`, `reaction`, `group`, or `typing` content.
+
+## Edits
+
+Rewrite the content of a previously-sent outbound message. Edits are fire-and-forget — `space.send(edit(...))` resolves to `undefined`.
+
+```ts
+import { edit, text } from "spectrum-ts";
+
+const sent = await space.send("Draft");
+await space.send(edit(text("Final version"), sent));
+```
+
+`edit()` cannot wrap `edit`, `reply`, `reaction`, `group`, or `typing` content.
+
+## Typing indicators
+
+Send a typing indicator signal through the content pipeline. Defaults to `"start"`.
+
+```ts
+import { typing } from "spectrum-ts";
+
+await space.send(typing());        // start typing
+await space.send(typing("stop"));  // stop typing
+```
+
+`space.startTyping()`, `space.stopTyping()`, and `space.responding(fn)` are sugar over `space.send(typing(...))`. Platforms without a typing-indicator API silently no-op.
 
 ## Composing multiple items
 
@@ -215,9 +253,9 @@ await space.send(
 
 This runs one `send()` per item on the underlying provider — not a single compound message. Reach for `group(...)` instead when you specifically want them rendered as one bundled unit.
 
-## Replies
+## Replies (sugar)
 
-`message.reply(...)` has the same variadic signature:
+`message.reply(...)` has the same variadic signature and delegates to `space.send(reply(...))` internally:
 
 ```ts
 await message.reply(
@@ -226,4 +264,4 @@ await message.reply(
 );
 ```
 
-On platforms without thread support, `reply()` resolves as a no-op. If you need guaranteed delivery, use `space.send(...)` instead.
+On platforms without thread support, `reply()` resolves as a no-op. If you need guaranteed delivery, use `space.send(...)` instead. See [Reactions and replies](/spectrum-ts/reactions-and-replies) for the canonical form and more details.

docs-src/spectrum-ts/custom-platforms.mdx.vel

@@ -50,30 +50,33 @@ export const myPlatform = definePlatform("my-platform", {
     destroyClient: async ({ client }) => { await client.disconnect(); },
   },
 
-  // Event streams
-  events: {
-    async *messages({ client }) {
-      for await (const msg of client.onMessage()) {
-        yield {
-          id: msg.id,
-          content: { type: "text", text: msg.body },
-          sender: { id: msg.authorId },
-          space: { id: msg.channelId },
-          timestamp: new Date(msg.ts),
-        };
-      }
-    },
+  // Inbound message stream
+  async *messages({ client }) {
+    for await (const msg of client.onMessage()) {
+      yield {
+        id: msg.id,
+        content: { type: "text", text: msg.body },
+        sender: { id: msg.authorId },
+        space: { id: msg.channelId },
+        timestamp: new Date(msg.ts),
+      };
+    }
   },
 
-  // Actions
-  actions: {
-    send: async ({ space, content, client }) => {
-      if (content.type === "text") {
-        await client.send(space.id, content.text);
-      }
-    },
-    // Optional:
-    // startTyping, stopTyping, reactToMessage, replyToMessage
+  // Outbound dispatcher — all content types flow through here
+  send: async ({ space, content, client }) => {
+    switch (content.type) {
+      case "text":
+        return await client.send(space.id, content.text);
+      case "reaction":
+        await client.react(space.id, content.target.id, content.emoji);
+        return;
+      case "reply":
+        return await client.reply(space.id, content.target.id, content.content);
+      case "typing":
+        await client.setTyping(space.id, content.state === "start");
+        return;
+    }
   },
 
   // Optional static properties
@@ -95,32 +98,34 @@ export const myPlatform = definePlatform("my-platform", {
 | `space.params` | No | Zod schema for additional space creation parameters — surfaces as the second arg to `platform(app).space()`. |
 | `lifecycle.createClient` | Yes | Creates the platform client. Receives `config`, `projectId`, `projectSecret` (both may be `undefined`), and `store`. |
 | `lifecycle.destroyClient` | No | Tears down the client on shutdown. Omit if no cleanup is needed. |
-| `events.messages` | Yes | Async generator that yields incoming messages. |
+| `messages` | Yes | Async generator that yields incoming messages. |
+| `send` | Yes | Dispatches a content item to a space. All content types — text, attachments, reactions, replies, edits, typing indicators — flow through this single action. Return a `ProviderMessageRecord` for content that produces a message, or `undefined` for fire-and-forget signals (reactions, typing, edits). |
+| `actions.getMessage` | No | Fetches a message by ID from a space. Powers `space.getMessage(id)`. |
 | `events.[custom]` | No | Additional async generators for platform-specific events — exposed on `app.[eventName]`. |
-| `actions.send` | Yes | Sends a single content item to a space. Invoked once per item when multiple are passed. |
-| `actions.startTyping` | No | Shows a typing indicator. |
-| `actions.stopTyping` | No | Hides a typing indicator. |
-| `actions.reactToMessage` | No | Reacts to a message. Missing → `message.react(...)` becomes a no-op. |
-| `actions.replyToMessage` | No | Sends a threaded reply. Missing → `message.reply(...)` becomes a no-op. |
 | `message.schema` | No | Zod schema for extra properties on incoming messages. |
 | `static` | No | Constants attached to the platform object (e.g. tapback names). |
 
 ## Event producers
 
 Every event generator receives `{ client, config, store }` and returns an `AsyncIterable`. The signature is <TypeTooltip name="EventProducer" type={`{{ ep.signature }}`} />.
 
+The core `messages` stream lives at the top level of the definition. Optional custom event streams (presence, read receipts, etc.) live inside `events`:
+
 ```ts
+// Top-level — required
+async *messages({ client }) { /* ... */ },
+
+// Optional custom events
 events: {
-  async *messages({ client }) { /* ... */ },
-  async *typing({ client }) {
-    for await (const ev of client.typing()) {
-      yield { spaceId: ev.chatId, userId: ev.user };
+  async *presence({ client }) {
+    for await (const ev of client.presence()) {
+      yield { spaceId: ev.chatId, userId: ev.user, online: ev.online };
     }
   },
 },
 ```
 
-Non-`messages` events are auto-wired as flat properties on both the Spectrum instance (`app.typing`) and the narrowed platform instance (`myPlatform(app).typing`).
+Custom events are auto-wired as flat properties on both the Spectrum instance (`app.presence`) and the narrowed platform instance (`myPlatform(app).presence`).
 
 ## Message extras
 

docs-src/spectrum-ts/messages.mdx.vel

@@ -123,6 +123,9 @@ for await (const [space, message] of app.messages) {
   | `"poll"` | `title: string`, `options: { title: string }[]` |
   | `"poll_option"` | `option: { title }`, `poll: Poll`, `selected: boolean`, `title: string` — sent as a vote |
   | `"group"` | `items: Message[]` — bundled multi-message unit |
+  | `"reply"` | `content: Content`, `target: Message` — threaded reply wrapping inner content |
+  | `"edit"` | `content: Content`, `target: Message` — rewrite of a previously-sent message |
+  | `"typing"` | `state: "start" \| "stop"` — typing indicator signal |
   | `"custom"` | `raw: unknown` — platform-specific structured data |
 </Accordion>
 

docs-src/spectrum-ts/reactions-and-replies.mdx.vel

@@ -5,11 +5,26 @@ description: "React to incoming messages and send threaded replies"
 
 Both `react` and `reply` live directly on an incoming message. They no-op silently on platforms that don't support the feature — no `try/catch` required.
 
+Spectrum also exports first-class `reaction()` and `reply()` content builders that you can pass directly to `space.send(...)` — the sugar methods on `message` delegate through the same `send` pipeline.
+
 ## Reactions
 
-```ts
-await message.react("love");
-```
+<Tabs>
+  <Tab title="Sugar (message.react)">
+    ```ts
+    await message.react("love");
+    ```
+  </Tab>
+  <Tab title="Canonical (space.send)">
+    ```ts
+    import { reaction } from "spectrum-ts";
+
+    await space.send(reaction("love", message));
+    ```
+  </Tab>
+</Tabs>
+
+Both forms are equivalent — `message.react(emoji)` delegates to `space.send(reaction(emoji, message))` internally.
 
 The reaction string is platform-specific. For iMessage, use the built-in tapback constants:
 
@@ -19,6 +34,8 @@ import { imessage } from "spectrum-ts/providers/imessage";
 await message.react(imessage.tapbacks.laugh);
 ```
 
+`reaction()` rejects reaction messages as targets — reacting to a reaction throws at build time.
+
 Available tapbacks:
 
 | Constant | Value |
@@ -32,25 +49,62 @@ Available tapbacks:
 
 ## Threaded replies
 
-`message.reply(...)` takes the same variadic content input as `space.send(...)`:
+<Tabs>
+  <Tab title="Sugar (message.reply)">
+    ```ts
+    await message.reply("Replying to your message.");
 
-```ts
-await message.reply("Replying to your message.");
+    await message.reply(
+      "Here's the attachment you asked for:",
+      attachment("/path/to/file.pdf"),
+    );
+    ```
+  </Tab>
+  <Tab title="Canonical (space.send)">
+    ```ts
+    import { reply, text } from "spectrum-ts";
 
-await message.reply(
-  "Here's the attachment you asked for:",
-  attachment("/path/to/file.pdf"),
-);
-```
+    await space.send(reply(text("Replying to your message."), message));
+    ```
+  </Tab>
+</Tabs>
+
+Both forms are equivalent — `message.reply(content)` wraps each content item in `reply(content, message)` and delegates to `space.send(...)` internally.
 
 On platforms with thread support (iMessage, WhatsApp Business), this sends a threaded reply. On platforms without, the call resolves as a no-op — **the reply is not downgraded to a regular send**. If you need guaranteed delivery, use `space.send(...)` instead.
 
+`reply()` cannot wrap `reply`, `edit`, `reaction`, `group`, or `typing` content — the builder throws at construction time.
+
+## Editing messages
+
+<Tabs>
+  <Tab title="Sugar (message.edit)">
+    ```ts
+    const sent = await space.send("Draft");
+    await sent.edit("Final version");
+    ```
+  </Tab>
+  <Tab title="Canonical (space.send)">
+    ```ts
+    import { edit, text } from "spectrum-ts";
+
+    const sent = await space.send("Draft");
+    await space.send(edit(text("Final version"), sent));
+    ```
+  </Tab>
+</Tabs>
+
+`edit()` takes new content and the outbound message to rewrite. Edits are fire-and-forget — `space.send(edit(...))` resolves to `undefined`.
+
+`edit()` cannot wrap `edit`, `reply`, `reaction`, `group`, or `typing` content.
+
 ## When to use what
 
 | Want to | Use |
 |---|---|
 | Send fresh content into the conversation | `space.send(...)` |
-| Reply in-thread to a specific message | `message.reply(...)` |
-| React to a specific message | `message.react(reaction)` |
+| Reply in-thread to a specific message | `message.reply(...)` or `space.send(reply(...))` |
+| React to a specific message | `message.react(emoji)` or `space.send(reaction(emoji, message))` |
+| Rewrite a sent message | `message.edit(content)` or `space.send(edit(content, message))` |
 
-`space.send` is the safe default — it works on every platform. Reach for `reply` when the threading behaviour is meaningful (e.g. replying in a busy group chat) and you're willing to accept the no-op on platforms that lack threads.
+`space.send` is the safe default — it works on every platform. The sugar methods (`message.reply`, `message.react`, `message.edit`) and the canonical content builders (`reply()`, `reaction()`, `edit()`) are interchangeable — they both route through the same `send` pipeline.

docs-src/spectrum-ts/spaces-and-users.mdx.vel

@@ -59,6 +59,8 @@ await space.startTyping();
 await space.stopTyping();
 ```
 
+These are sugar for `space.send(typing("start"))` and `space.send(typing("stop"))` — see [Content](/spectrum-ts/content#typing-indicators) for the canonical form.
+
 ### Automatic with `responding`
 
 `responding` is the recommended pattern. It guarantees the typing indicator is cleared even if the inner function throws:

package.json

@@ -27,7 +27,7 @@
     "eslint-plugin-format": "^2.0.1",
     "husky": "^9.1.7",
     "oxfmt": "^0.44.0",
-    "spectrum-ts": "1.4.0",
+    "spectrum-ts": "1.5.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3"
   }