firtoz/cf-socka-realtime

Socka realtime (Durable Objects + web)

When to use

• Adding or changing WebSocket RPC, server push, or per-room Durable Object state in this monorepo.
• Canvas / whiteboard / collaborative tools (patterns below are documentation; implement to product needs).

Rule of thumb: Prefer @firtoz/socka and a shared contract package; do not hand-roll { t: "…" } JSON protocols unless the user explicitly wants raw WebSockets. See cf-realtime-websockets.mdc.

Canonical reference in this repo

| Piece | Where | | ----- | ----- | | defineSocka contract (calls + pushes) | packages/chat-contract/src/contract.ts | | DO extending SockaWebSocketDO | durable-objects/chatroom-do/workers/chatroom-do.ts | | Web worker: upgrade → DO /websocket | apps/web/workers/app.ts | | Client useSockaSession + URL from current host | apps/web/app/components/chat/ChatClient.tsx | | Route-safe wss:// / ws:// builder | apps/web/app/lib/chat-ws-url.ts |

After bunx turbo gen durable-object: the default template is Hono + optional WebSocket forwarding; for Socka + DO SQLite, copy the chatroom pattern (chatroom-do + @internal/chat-contract) and renames described in project-init/SKILL.md for forks. A dedicated Socka codegen path may be added later.

SSR-safe WebSocket URL

• Never call window, window.location, or build wss:// in loaders, actions, or component render on paths that run under SSR.
• On the client, prefer deriving the WebSocket origin from the current page:

const url = new URL(window.location.href);
url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
url.pathname = "/api/your/prefix/room-id";
// …search params as needed

• Do not use fake fallbacks like ws://127.0.0.1/... to satisfy a hook. If a hook needs a URL immediately, mount a child component only after the client has a real URL, or show a loading shell until then.

• Match exactly the path prefix handled in apps/web/workers/app.ts before React Router (and do not break Vite HMR upgrades).

Live draft vs committed state (e.g. whiteboards)

For drawing apps, separate:

• Transient in-progress updates — e.g. sendDraft / push draftUpdated (in-progress stroke, uncommitted).
• Durable or canonical ops — e.g. applyOp / push opApplied after commit (persisted, undo stack, etc.).

Optionally batch or throttle cursor/presence on its own channel so it does not fight stroke traffic. This avoids “nothing appears until mouseup” for remote users.

Canvas / whiteboard acceptance (product demos)

For interactive canvas features, expect (unless scoped otherwise):

• Drawing appears during pointer drag (not only on release).
• Remote draft state appears before commit where applicable.
• Hit testing for select tool; selected shape can move; selection affordances are clear.
• Local vs remote cursors share a coherent visual language; “trails” behave as trails/glows, not one-off static stamps.

Testing: fetch and unit tests do not catch pointer bugs. Prefer browser automation (e.g. Cursor cursor-ide-browser MCP or Playwright): pointer down / move / up on the canvas, then assert visual or DOM/canvas state. See multiworker-workflow/SKILL.md for when typecheck is not enough.

Fire-and-forget Socka calls

Socka send.* returns promises. In hot paths (pointer move, requestAnimationFrame, intervals), handle rejections so browser tests and users do not see uncaught promise errors:

void send.sendCursor(...).catch(() => undefined);

Pre-merge checklist (realtime features)

• [ ] Shared contract exists (defineSocka); no ad-hoc JSON wire protocol unless justified.
• [ ] No window / document in SSR render paths for WebSocket URLs.
• [ ] No fake localhost / 127.0.0.1 / placeholder WebSocket URLs as runtime fallbacks.
• [ ] If applicable: live draft path and committed op path are both defined; presence/cursor path if required.
• [ ] Browser interaction or automation exercised for the flow; no unexplained console errors.
• [ ] bun run typegen (if routes/bindings changed), bun run typecheck, bun run lint from repo root per multiworker-workflow/SKILL.md.

Related

• Durable Object package layout: cf-durable-object-package/SKILL.md
• Web bindings and worker forwarding: cf-web-alchemy-bindings/SKILL.md
• Generated / AI image assets in UI: component-organization/SKILL.md (mockups and raster usage)