Skip to content

garethpaul/poe-games-procedural-dungeons / .claude/skills/synced-store

synced-store

Verified

Build apps that USE synced-store for real-time multiplayer state. PROACTIVELY load when: designing a new Poe tile's state/schema (even before any file exists), discussing how to hide, gate, or restrict visibility of data to specific users or to the server, writing schema.ts/mutators/*.ts/client-config.ts/backend-config.ts for a Poe tile, using createPoeTileTestHarness, calling store.subscribe/store.mutate, or wiring entry.tsx with setupStore.

references/server-forking.md

View on GitHub
<!-- owner: jyoung-q -->
# Forking Mutator Logic with `ctx.isServer`

Mutators run on both the client (optimistically) and the server (authoritatively). `ctx.isServer` lets you branch behavior between those two runs. Use it sparingly — the whole point of mutators is that the two runs converge.

## Legitimate Uses

### Pending Indicators

Show a "pending" state on the client that disappears when the server confirms:

```typescript
sendMessage: async (ctx, input) => {
  await ctx.table("messages").set({
    itemKey: input.id,
    value: {
      text: input.text,
      isPending: !ctx.isServer,  // true on client, false on server
    },
  });
},
```

The optimistic client write sets `isPending: true`; when the server run lands, its write replaces the row with `isPending: false`. The UI can render a subtle "sending..." indicator on pending items.

### Server-Only Writes

Writes to `ctx.serverOnly()` throw on the client. Guard them:

```typescript
joinRound: async (ctx, input) => {
  await ctx.table("players").set({
    itemKey: ctx.userId,
    value: { name: input.name, score: 0 },
  });

  if (ctx.isServer) {
    await ctx.serverOnly().table("audit").set({
      itemKey: ctx.userId,
      value: { joinedAt: Date.now() },
    });
  }
},
```

### Cross-User Private Writes

`ctx.privateOfUser(otherUserId)` throws on the client when the target isn't `ctx.userId` (see [data-visibility.md](data-visibility.md) access matrix). Guard with `ctx.isServer`:

```typescript
startRound: async (ctx) => {
  // Validate on both sides so invalid calls fail fast on the caller's UI.
  const players = (await ctx.table("players").entries().toArray()).map(([, v]) => v);
  const redSpymaster = players.find((p) => p.team === "red" && p.role === "spymaster");
  if (!redSpymaster) throw new Error("need a red spymaster");

  // Cross-user private writes (and any non-deterministic generation) are
  // server-only. The caller's UI shows a brief "starting..." state until
  // the server-confirmed writes arrive.
  if (!ctx.isServer) return;

  const colors = assignColors();  // Math.random — server-only is fine
  for (const { index, color } of colors) {
    await ctx.privateOfUser(redSpymaster.userId).table("cardColors").set({
      itemKey: String(index),
      value: { index, color },
    });
  }
},
```

### Skip Optimistic Entirely When the Outcome Depends on Unreadable Data

Sometimes a mutator's outcome depends on data the caller can't read — another user's `privateOfUser` scope, or a `serverOnly` table. The client can't compute the full result, so any optimistic write is partial and the UI has to render an ambiguous in-between state. Usually cleaner to skip optimistic entirely:

```typescript
revealCard: async (ctx, input) => {
  // Validate on both sides so stale clicks (wrong phase / inactive team)
  // fail fast on the caller's UI.
  const phase = await ctx.table("game").get("phase");
  if (phase !== "guessing") throw new Error(`bad phase: ${phase}`);
  // ... other validation

  // Outcome depends on reading a spymaster's private scope — caller can't.
  // Skip optimistic; the click takes ~1 round-trip but the state transition
  // is a single clean step (unrevealed → fully-resolved) instead of a
  // half-filled flicker.
  if (!ctx.isServer) return;

  const color = await ctx.privateOfUser(spymasterId).table("cardColors").get(...);
  await ctx.table("cards").set({ itemKey, value: { revealed: true, revealedAs: color } });
  // ... update scores / switch turn / check winner
},
```

The alternative is to write a structured "pending" marker like in the [Pending Indicators](#pending-indicators) pattern — use that only when the UI benefits enough from immediate feedback to justify rendering a partial state explicitly. Never write a half-filled state (e.g., `revealed: true` but `revealedAs: null`) without a marker field the UI checks.

### Not Needed For `ctx.enqueueAction`

`ctx.enqueueAction(...)` is already a no-op on the client — call it unconditionally, no `ctx.isServer` guard required. The action only runs on the server after the triggering mutation commits.

```typescript
// ✅ No guard needed
ctx.enqueueAction("generateWithAI", { id, prompt });

// ❌ Redundant — enqueueAction is already a client no-op
if (ctx.isServer) {
  ctx.enqueueAction("generateWithAI", { id, prompt });
}
```

## Don't Do This

- **Don't put expensive client-only work inside `!ctx.isServer`.** If the work is client-only, do it in the UI layer, not inside the mutator.
- **Don't fork to work around non-determinism — usually.** If you're tempted to use `Date.now()` or `Math.random()` in one branch, pass the value as mutator input instead (the caller generates once; both client and server runs see the same value). **Exception:** when the non-deterministic value must stay hidden from the caller — e.g., generating a Spy Words color assignment a guesser is about to click through. Passing the seed as input would let the caller read it from their own local mutation log. In that case, put the generation behind `if (!ctx.isServer) return;` (see [Skip Optimistic Entirely](#skip-optimistic-entirely-when-the-outcome-depends-on-unreadable-data) above) and accept the ~1 round-trip latency.
- **Don't use `ctx.isServer` to reach different data conclusions** (e.g. reading different tables on client vs server). The two runs must converge on the same state.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall