@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/skills/grok-generate2dsprite/scripts/make_layout_guide.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""Create a layout-only guide image for sprite sheet generation."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from PIL import Image, ImageDraw
+
+
+def draw_dashed_line(
+    draw: ImageDraw.ImageDraw,
+    start: tuple[int, int],
+    end: tuple[int, int],
+    *,
+    fill: str,
+    width: int,
+    dash: int,
+    gap: int,
+) -> None:
+    x1, y1 = start
+    x2, y2 = end
+    if x1 == x2:
+        for y in range(min(y1, y2), max(y1, y2), dash + gap):
+            draw.line((x1, y, x2, min(y + dash, max(y1, y2))), fill=fill, width=width)
+        return
+    if y1 == y2:
+        for x in range(min(x1, x2), max(x1, x2), dash + gap):
+            draw.line((x, y1, min(x + dash, max(x1, x2)), y2), fill=fill, width=width)
+        return
+    raise ValueError("draw_dashed_line only supports horizontal or vertical lines")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--rows", type=int, required=True)
+    parser.add_argument("--cols", type=int, required=True)
+    parser.add_argument("--cell-width", type=int, default=384)
+    parser.add_argument("--cell-height", type=int, default=384)
+    parser.add_argument("--safe-margin-x", type=int, default=52)
+    parser.add_argument("--safe-margin-y", type=int, default=52)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument(
+        "--label-cells",
+        action="store_true",
+        help="Draw small row,column labels. Leave off for normal imagegen references.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    if args.rows <= 0 or args.cols <= 0:
+        raise SystemExit("--rows and --cols must be positive")
+    if args.cell_width <= 0 or args.cell_height <= 0:
+        raise SystemExit("--cell-width and --cell-height must be positive")
+
+    width = args.cols * args.cell_width
+    height = args.rows * args.cell_height
+    image = Image.new("RGB", (width, height), "#f8f8f8")
+    draw = ImageDraw.Draw(image)
+
+    for row in range(args.rows):
+        for col in range(args.cols):
+            left = col * args.cell_width
+            top = row * args.cell_height
+            right = left + args.cell_width - 1
+            bottom = top + args.cell_height - 1
+            safe_left = left + args.safe_margin_x
+            safe_top = top + args.safe_margin_y
+            safe_right = right - args.safe_margin_x
+            safe_bottom = bottom - args.safe_margin_y
+
+            draw.rectangle((left, top, right, bottom), outline="#111111", width=4)
+            draw.rectangle(
+                (safe_left, safe_top, safe_right, safe_bottom), outline="#2f80ed", width=3
+            )
+
+            center_x = left + args.cell_width // 2
+            center_y = top + args.cell_height // 2
+            draw_dashed_line(
+                draw,
+                (center_x, safe_top),
+                (center_x, safe_bottom),
+                fill="#b8b8b8",
+                width=2,
+                dash=14,
+                gap=16,
+            )
+            draw_dashed_line(
+                draw,
+                (safe_left, center_y),
+                (safe_right, center_y),
+                fill="#b8b8b8",
+                width=2,
+                dash=14,
+                gap=16,
+            )
+
+            if args.label_cells:
+                draw.text((left + 12, top + 10), f"{row + 1},{col + 1}", fill="#777777")
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    image.save(args.output)
+
+
+if __name__ == "__main__":
+    main()

package/skills/grok-imagine/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: imagine
+description: >
+  How to use the Imagine tools in Grok Build: imagine_text_to_image,
+  imagine_image_to_image, imagine_reference_to_image, imagine_text_to_video,
+  imagine_image_to_video, imagine_reference_to_video, and render_file for chat
+  previews. When to build a visual with code instead of generating it,
+  prompt-craft, reference-first handling of real people, factual grounding, and
+  asset-consistency. Load this whenever generating or editing an image or video
+  is on the table. Tool-usage-driven, not triggered by a user merely mentioning
+  images.
+metadata:
+  short-description: "Prompting and workflow guidance for Imagine image/video tools"
+user-invocable: false
+---
+
+# Imagine
+
+Grok Build uses the **split Imagine computer stack** (`grok_computer` variants).
+There is **no** consolidated `imagine_image` or `imagine_video` tool — always
+call the modality-specific name from the table below.
+
+| Tool | Role |
+|------|------|
+| `imagine_text_to_image` | New image from a text prompt only (no source). |
+| `imagine_image_to_image` | Edit / restyle **one** existing image (sandbox path). |
+| `imagine_reference_to_image` | Combine **2+** reference images (sandbox paths). |
+| `imagine_text_to_video` | New video from a text prompt only (no source). |
+| `imagine_image_to_video` | Animate **one** still (sandbox path) into a video. |
+| `imagine_reference_to_video` | Video from **1+** reference images (sandbox paths). |
+| `render_file` | Show a sandbox image/video path to the user in chat. |
+
+**Path-based handles.** These tools read/write the shared sandbox:
+
+- Generation returns a sandbox **`file_path`** (under artifacts). Open it with
+  `read_file` / shell; show the user with **`render_file`**.
+- Edit / animate tools take that path (or paths) as input — match the live
+  schema (`image`, `images`, etc.). Never invent paths.
+- Never call `imagine_image` / `imagine_video`. Asset-id helpers
+  (`imagine_create_asset` / `imagine_view_media` / `render_imagine_media`) are
+  **not** on this stack.
+
+Apply this whenever you're considering or about to call any of these tools.
+
+## Handle flow (mandatory mental model)
+
+```text
+generate → file_path → render_file (show user) / read_file or scripts (QC)
+edit / animate → pass prior file_path(s) into image_to_* / reference_to_*
+```
+
+- **Use the path the tool actually returned** — do not invent filesystem paths.
+- **Show the user media** with `render_file`, not ad-hoc markdown image links.
+
+## Build accurate visuals with code, not the image tools
+
+1. **Image models are unreliable at exact text, numbers, and structure.** They can handle short text or a simple layout, but they often garble words, invent numbers, draw chart bars that match no data, or point diagram arrows nowhere, and the more that has to be exact, the worse they do. A detailed prompt doesn't make it dependable, and another `imagine_image_to_image` edit usually won't fix it. So when a result needs specific text, data, or structure to be correct (charts from real numbers, labeled or technical diagrams, math explainers, tables, screens with real copy), construct the asset with code, where you control the exact content. Prefer HTML and CSS, which give much better layout, typography, and polish than Python plotting. When only the look matters (photos, illustrations, characters, scenes, decorative art), the image tools are the right choice. Which one fits depends on what the output needs to get right, not on how the request is worded.
+
+## Verifying discrete accuracy (loop)
+
+When the output must get specific text, numbers, data, or structure right, don't trust the first result - verify it in a loop:
+
+1. Produce the result (generate, or per *Build accurate visuals with code*, construct it in code).
+2. Inspect the actual output - use `read_file` (image understanding) on the result path - and confirm every word, number, label, and structural detail matches the requirement, and that nothing overlaps, clips, or runs off-canvas.
+3. If anything is wrong, fix and re-verify:
+   - Garbled text, invented numbers, or broken layout from an image model? Don't just re-prompt - it will likely garble it again. Rebuild it with code.
+   - Overlapping or clipped elements in code-built output? Re-lay-out with auto-layout (HTML/CSS) rather than nudging coordinates by hand.
+   - Otherwise make one targeted edit via `imagine_image_to_image` with the prior path.
+4. Only finish when the discrete content is exactly correct. If it can't be made accurate, tell the user instead of shipping something wrong.
+
+## Core Principles
+
+1. **You own the prompt.** If the user gives a detailed prompt or asks you to use theirs, use it verbatim. Otherwise craft the final prompt: front-load the subject, give strong high-level direction for mood, composition, lighting, and style without over-specifying every detail, write natural prose rather than keyword tags, and describe positively instead of using negative prompts. For edits, describe only what changes. Target 2-5 sentences.
+2. **Reference-first for real people.** Never use pure text-to-image for a named real person or group, including face swaps, posters, cartoons, and cinematic or editorial depictions. Use `imagine_image_to_image` **with a real reference path** instead, and never produce non-consensual, sexualized, or minor-involving likenesses. See Real People and References for the procedure.
+3. **Ground facts with search first.** If any part of the request depends on a real-world fact, identity, brand or product, place, event, or top/latest/current result, search the web before generating and put the actual verified details into the prompt. Don't rely on memory, and don't write vague placeholders like "the current president"; write the verified name.
+4. **Reuse a base for consistency.** When the same character, object, or setting must appear across multiple images, generate one base with `imagine_text_to_image`, keep its `file_path`, then pass that path to `imagine_image_to_image` for every variation. Don't re-run text-to-image from scratch for a recurring subject.
+5. **Handle failures gracefully.** On a moderation or safety block, stop; don't retry and don't paraphrase the prompt to evade the filter. Tell the user it was blocked and offer a different direction. If a reference is weak or a result looks off-target, say so and ask for an upload or redirect rather than silently iterating.
+6. **Plan multi-step workflows.** Sequence the steps; only parallelize generations that belong to the same step.
+7. **Review at the end.** Confirm the generations you intended actually executed and match what was asked. Render final assets with `render_file`.
+8. **Don't assume tool behavior.** Don't invent tool parameters, return values, or environment capabilities that aren't actually provided; verify rather than guess.
+
+## Choosing the tool
+
+| Situation | Call |
+|-----------|------|
+| New image, no source | `imagine_text_to_image` with `prompt` (+ `aspect_ratio`) |
+| Edit / restyle / recolor one existing image | `imagine_image_to_image` with `prompt` + source path |
+| Combine 2+ reference images into one | `imagine_reference_to_image` with `prompt` + source paths |
+| Iterate on a previous result | `imagine_image_to_image` with prior path |
+| Named real person or group | `imagine_image_to_image` with a real reference path after web search |
+| Generic / invented subject from scratch | `imagine_text_to_image` |
+| New video, no source | `imagine_text_to_video` with `prompt` |
+| Animate one still | `imagine_image_to_video` with that still's path |
+| Multi-ref video | `imagine_reference_to_video` with image path(s) |
+
+Rule of thumb: **no refs → text_to_*; one ref → image_to_*; 2+ refs → reference_to_*.**
+
+## `imagine_text_to_image`
+
+Generate a new image from a text prompt.
+
+Inputs:
+
+- `prompt` (required) - full description of the desired image.
+- `aspect_ratio` - one of `1:1`, `3:4`, `4:3`, `2:3`, `3:2`, `9:16`, `16:9`, `21:9`, `5:2`, `50:11`, or `unknown`. Use `16:9` for OG share cards and `50:11` for the X feed banner when generating a custom `public/x-banner.jpg` for **games** (every app wires `x:game:image`; only games call Imagine for it — see the `og` skill); for a true 2:1 canvas, call the xAI Images API.
+
+To produce multiple variations, make multiple `imagine_text_to_image` calls with distinct prompts. The tool does not expose `n` or `count` parameters.
+
+## `imagine_image_to_image`
+
+Edit one existing image.
+
+Inputs (names follow the live schema — typically a singular sandbox path):
+
+- `prompt` (required) - what to change (describe only the edit).
+- Source path field (required) - sandbox path returned by a prior generation or download.
+- `aspect_ratio` - only set when the user explicitly wants a ratio change.
+
+## `imagine_reference_to_image`
+
+Compose one image from 2+ reference paths.
+
+Inputs:
+
+- `prompt` (required).
+- Source paths (required) - 2+ sandbox paths.
+- `aspect_ratio` - optional.
+
+For a single source edit, use `imagine_image_to_image` instead.
+
+## `imagine_text_to_video`
+
+Generate a new video from a text prompt only (no source frame).
+
+Inputs:
+
+- `prompt` (required) - short present-tense shot description.
+- `duration` / `aspect_ratio` / resolution fields as exposed by the live schema.
+
+Prefer short shots; same prompt-craft rules as image-to-video below.
+
+## `imagine_image_to_video`
+
+Animate one still into a video.
+
+Inputs:
+
+- Singular source still path (required).
+- `prompt` - short present-tense shot (recommended; required by some variants).
+- `duration` - `6` (default), `10`, or `15` when exposed.
+- `aspect_ratio` - optional; omit to keep the source ratio when animating one image.
+
+**Prefer short shots.** Build video as a planned sequence of short clips, not one long take:
+
+1. Plan the story as shots - one beat each.
+2. Prefer more 6s shots over fewer long ones.
+3. Create each shot's source still with `imagine_text_to_image` / `imagine_image_to_image` (keep character paths consistent).
+4. Animate with `imagine_image_to_video` + that still path.
+
+Key behaviors:
+
+- **Prompt-craft:** one short, vivid moment in present tense with a clear camera movement, in 1-2 sentences.
+- **Minimal but interesting:** one clear subject and a single simple motion or camera move.
+- **Complex source?** Keep the subject fixed and move only the camera, or break into simpler shots.
+- **Real people:** reference-first - drive from a verified reference; never animate a named person without one.
+- Don't loop the same clip unless asked.
+- Assemble multi-shot timelines with FFmpeg stream copy on the returned video paths.
+
+## `imagine_reference_to_video`
+
+Video from one or more reference image paths guided by a prompt. Prefer composing a single still with `imagine_reference_to_image` first, then `imagine_image_to_video`, when the goal is a clean first frame.
+
+## Writing Strong Prompts
+
+Describe, roughly in this order: **subject -> action/pose -> setting -> style -> composition -> lighting/mood -> key details.**
+
+- Be specific and concrete; lead with the most important elements.
+- State what to include rather than what to exclude.
+- Use one coherent scene per prompt.
+- Match `aspect_ratio` to the use case: `9:16` for phone/story, `16:9` for banner/video frame or OG share cards, `1:1` for avatar/icon.
+
+## Real People and References
+
+1. Search the web first to confirm identity, role, relationship, or event, even when it seems obvious.
+2. Obtain a strong reference image on disk (user upload or search → sandbox path), then call `imagine_image_to_image` with that path. A user-uploaded photo is best.
+3. If no suitable reference exists, ask the user to upload one rather than generating from a weak base.
+
+## Showing results
+
+- Call `render_file` with the sandbox `file_path` so the user sees the image/video in chat.
+- For your own QC and scripts, `read_file` / shell on that path.
+
+Game sprites and maps have their own pipelines — follow `generate2dsprite`,
+`video2dsprite`, and `generate2dmap` for those.
+
+## Failure modes to avoid
+
+- Calling consolidated names `imagine_image` or `imagine_video` (they are not available).
+- Passing a list to `imagine_image_to_image` / `imagine_image_to_video` (singular source only).
+- Inventing a filesystem path that the tool never returned.
+- Running chroma/ffmpeg on a path you made up without a real generation/`file_path`.

package/skills/grok-imagine/agentsam.skill.json

@@ -0,0 +1,25 @@
+{
+  "schema": "agentsam.skill.v1",
+  "id": "grok-imagine",
+  "name": "Grok \u00b7 imagine",
+  "description": "Prompting and workflow guidance for Imagine image/video tools",
+  "icon": "skill",
+  "slash": {
+    "suggested": "/grok-imagine"
+  },
+  "instructions": {
+    "source": "local_file",
+    "ref": "SKILL.md"
+  },
+  "execution": {
+    "mode": "turn",
+    "tools": [],
+    "operations": [],
+    "capabilities": []
+  },
+  "provenance": {
+    "source": "apps/local-studio/.grok/skills",
+    "vendor": "grok",
+    "status": "imported"
+  }
+}

package/skills/grok-multiplayer-p2p/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: multiplayer-p2p
+description: >
+  Peer-to-peer realtime multiplayer over WebRTC data channels: every user of
+  the deployed app connects directly to every other user (full mesh), the
+  server only brokers the handshake at /api/rtc. Lowest possible latency, zero
+  per-message server cost. Use for 2-8 player co-op/casual realtime: shared
+  cursors, drawing, party games, casual action. Triggers: p2p, peer to peer,
+  webrtc, low latency multiplayer, direct connection.
+metadata:
+  short-description: "WebRTC P2P mesh, signaled at /api/rtc"
+user-invocable: false
+---
+
+# Multiplayer (WebRTC peer-to-peer)
+
+All visitors on the same deployed domain join one default room, opening a
+native WebRTC data channel directly to every other visitor — game traffic
+itself never touches a server. A tiny relay at `/api/rtc` handles only the
+routing of the connection handshake (SDP/ICE) while peers connect. What you
+use from the kit is client-side only; the relay is yours.
+
+Latency is browser↔browser (often 5–40ms) with zero per-tick server cost.
+
+| Piece | Path |
+|---|---|
+| Mesh primitive (start here) | `P2PRoom` from `@/lib/multiplayer` |
+| React room binding (optional, you create) | `src/lib/multiplayer/use-p2p-room.ts` |
+| Signaling relay (you create) | `src/lib/multiplayer/signaling.server.ts` |
+| HTTP mount (you create) | `src/routes/api/rtc.ts` |
+
+**Trust model — read before choosing P2P.** There is no server authority:
+every peer runs its own copy of the rules and can lie (position, score,
+anything). Peers also learn each other's IP addresses during ICE. P2P is for
+**co-op and casual play among people who choose to play together** — never for
+competitive ranking, cheat-sensitive, or anonymous-stranger matchmaking.
+Competitive or cheat-sensitive play is not supported in this template: push
+back in product terms rather than shipping it on P2P.
+
+Practical limits: a full mesh is O(N²) connections — cap rooms at ~8 peers.
+Roughly 10–20% of peer pairs sit behind strict NATs and cannot connect; the
+kit surfaces this per peer as `connectionState: "failed"` — show it in the
+UI rather than hanging.
+
+## Setup (once)
+
+Create the two server files — nothing works without them:
+
+1. `src/lib/multiplayer/signaling.server.ts` — the DB-backed signaling relay
+   (Neon deployed, PGLite in preview).
+2. `src/routes/api/rtc.ts` — mounts it at `/api/rtc` (GET poll, POST
+   signal/leave).
+
+**Copy both from `references/signaling-relay.md`**, which also carries the
+schema note: the relay creates its own two tables on first use
+(`CREATE TABLE IF NOT EXISTS`), so **nothing goes in `migrations/`** unless you
+deliberately want to own the schema.
+
+## Using the primitive
+
+`P2PRoom` is framework-free, and a "room" is just a rendezvous key — a lobby
+code, a 1:1 call id, a shared-document id, any string (≤64 chars). Any
+architecture sits on top of the same three calls:
+
+```ts
+import { P2PRoom } from "@/lib/multiplayer";
+
+const p2p = new P2PRoom({
+  room: "doc-42",
+  selfId: myId,
+  name: "ani",
+  onPeersChanged: (peers) => render(peers),
+  onMessage: (from, data, channel) => apply(from, data, channel),
+});
+await p2p.join();
+p2p.broadcast(state); // unreliable "state" channel — game-rate, stale drops
+p2p.send(event, to); // reliable channel — exactly-once events (to optional)
+p2p.close();
+```
+
+For the common "everyone on this app plays together" shape in React, copy the
+`useP2PRoom` hook (plus a worked component: game-rate broadcast loop at ~20
+sends/s, reliable one-shot events) from `references/react-binding.md`.
+
+Patterns:
+
+1. `broadcast()` = unreliable/unordered, for continuously-refreshed state
+   (positions, cursors). `send()` = reliable/ordered, for events that must
+   arrive exactly once. Never stream game-rate state on `send()`; interpolate
+   between broadcasts for smooth motion.
+2. Late joiners know nothing: on a new peer appearing in `p2p.peers`, an
+   existing peer should `send()` it the current shared state. Exactly one
+   peer must answer: compare ids among the peers that were ALREADY in the
+   room (your `selfId` plus `p2p.peers` minus the newcomer) and answer only
+   if your `selfId` is the smallest — so two simultaneous joiners neither
+   double-answer nor go unanswered.
+3. Room ids: omit for "everyone on this app plays together"; pass
+   `room: code` for private lobbies (generate a short code, put it in the URL).
+4. Peers disappear without goodbye (tab close, sleep): treat a peer missing
+   from `p2p.peers` as gone and drop its entities.
+5. A React binding that captures `room`/`name` on first render (the one in
+   `references/react-binding.md` does) needs a remount to change them — key the
+   component on the room code.
+
+## Diagnostics
+
+Each entry in `p2p.peers` carries `connectionState`, `rttMs` (data-channel
+ping), and `candidateType` (`host`/`srflx` = direct). To override STUN, add
+`VITE_STUN_URLS` (comma-separated) to `.grok/app-env.json` and **restart the dev
+server** (Vite reads env at startup; HMR will not pick it up) — never write a
+`.env` in this sandbox.

package/skills/grok-multiplayer-p2p/agentsam.skill.json

@@ -0,0 +1,25 @@
+{
+  "schema": "agentsam.skill.v1",
+  "id": "grok-multiplayer-p2p",
+  "name": "Grok \u00b7 multiplayer-p2p",
+  "description": "WebRTC P2P mesh, signaled at /api/rtc",
+  "icon": "skill",
+  "slash": {
+    "suggested": "/grok-multiplayer-p2p"
+  },
+  "instructions": {
+    "source": "local_file",
+    "ref": "SKILL.md"
+  },
+  "execution": {
+    "mode": "turn",
+    "tools": [],
+    "operations": [],
+    "capabilities": []
+  },
+  "provenance": {
+    "source": "apps/local-studio/.grok/skills",
+    "vendor": "grok",
+    "status": "imported"
+  }
+}

package/skills/grok-multiplayer-p2p/references/react-binding.md

@@ -0,0 +1,144 @@
+# React room binding (optional — copy if it fits your app)
+
+For the common "everyone on this app plays together" shape, copy this hook to
+`src/lib/multiplayer/use-p2p-room.ts` and adapt it freely — it is yours, not
+part of the kit. It captures `room`/`name` on first render, so changing them
+later requires remounting the component (key it on the room code).
+
+
+```ts
+/**
+ * React binding for P2PRoom. Identity and room id are captured once on mount
+ * (useState initializers) so re-renders never tear down the mesh: the P2PRoom
+ * instance lives exactly as long as the component that mounted it, and
+ * changing `room`/`name` requires a remount (key the component on them).
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { P2PRoom, type PeerInfo } from "./p2p";
+
+export interface UseP2PRoomOptions {
+  /** Defaults to a per-deployment room derived from the hostname. */
+  room?: string;
+  name?: string;
+}
+
+export interface P2PRoomHandle {
+  selfId: string;
+  room: string;
+  /** Remote peers only (self excluded), with live connection diagnostics. */
+  peers: PeerInfo[];
+  joined: boolean;
+  /** Unreliable game-state fanout to every connected peer. */
+  broadcast: (data: unknown) => void;
+  /** Reliable ordered send to one peer (or all when peerId is omitted). */
+  send: (data: unknown, peerId?: string) => void;
+  /** Subscribe to incoming messages; returns an unsubscribe function. */
+  onMessage: (
+    fn: (from: string, data: unknown, channel: "state" | "reliable") => void,
+  ) => () => void;
+}
+
+function defaultRoom(): string {
+  if (typeof window === "undefined") return "room-ssr";
+  // DNS labels can be 63 chars; the signaling ID regex caps room ids at 64 —
+  // truncate so `room-` + label always fits.
+  return `room-${window.location.hostname.split(".")[0]}`.slice(0, 64);
+}
+
+export function useP2PRoom(options: UseP2PRoomOptions = {}): P2PRoomHandle {
+  const [selfId] = useState(() => `p-${Math.random().toString(36).slice(2, 10)}`);
+  const [room] = useState(() => options.room ?? defaultRoom());
+  const [name] = useState(() => options.name ?? selfId);
+  const [peers, setPeers] = useState<PeerInfo[]>([]);
+  const [joined, setJoined] = useState(false);
+  const roomRef = useRef<P2PRoom | null>(null);
+  const listeners = useRef(
+    new Set<(from: string, data: unknown, channel: "state" | "reliable") => void>(),
+  );
+
+  useEffect(() => {
+    const p2p = new P2PRoom({
+      room,
+      selfId,
+      name,
+      onPeersChanged: setPeers,
+      onMessage: (from, data, channel) => {
+        for (const fn of listeners.current) fn(from, data, channel);
+      },
+      // `joined` flips on the FIRST successful poll — join() itself resolves
+      // even when the first poll fails (the loop keeps retrying).
+      onConnected: () => setJoined(true),
+    });
+    roomRef.current = p2p;
+    void p2p.join();
+    return () => {
+      roomRef.current = null;
+      p2p.close();
+    };
+  }, [room, selfId, name]);
+
+  // Stable identities (both close over refs) so consumers can safely list
+  // these in effect deps without re-subscribing every render.
+  const broadcast = useCallback((data: unknown) => roomRef.current?.broadcast(data), []);
+  const send = useCallback(
+    (data: unknown, peerId?: string) => roomRef.current?.send(data, peerId),
+    [],
+  );
+  const onMessage = useCallback(
+    (fn: (from: string, data: unknown, channel: "state" | "reliable") => void) => {
+      listeners.current.add(fn);
+      return () => {
+        listeners.current.delete(fn);
+      };
+    },
+    [],
+  );
+
+  return { selfId, room, peers, joined, broadcast, send, onMessage };
+}
+```
+
+
+Used in a component:
+
+
+```tsx
+import { useP2PRoom } from "@/lib/multiplayer";
+
+function Game() {
+  const p2p = useP2PRoom({ name: "ani" }); // room defaults per deployment
+  const [positions, setPositions] = useState<Record<string, Pos>>({});
+
+  useEffect(
+    () =>
+      p2p.onMessage((from, data, channel) => {
+        if (channel === "state") {
+          setPositions((p) => ({ ...p, [from]: data as Pos }));
+        }
+      }),
+    [p2p.onMessage],
+  );
+
+  // Game-rate state: broadcast on the unreliable channel (stale packets drop).
+  // 20-30 sends/s is plenty; interpolate between updates for smooth motion.
+  useEffect(() => {
+    let raf = 0;
+    let lastSent = 0;
+    const loop = (now: number) => {
+      if (now - lastSent >= 50) {
+        // ~20 sends/s
+        p2p.broadcast(myPositionRef.current);
+        lastSent = now;
+      }
+      raf = requestAnimationFrame(loop);
+    };
+    raf = requestAnimationFrame(loop);
+    return () => cancelAnimationFrame(raf);
+  }, [p2p.broadcast]);
+
+  // One-shot actions (chat, "start game"): reliable + ordered.
+  const sendChat = (text: string) => p2p.send({ chat: text });
+
+  return <Board peers={p2p.peers} positions={positions} />;
+}
+```