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/testing-network-control.md

View on GitHub
<!-- owner: jyoung-q -->
# Testing: Network Control

The test harness gives you full control over network timing, letting you test optimistic updates, race conditions, reordering, and offline behavior — deterministically, with no real timers or real network connections.

## Creating a Controlled Client

Use `createControlledClient()` to get a `transport` handle with manual flush control. Messages queue on both outbound (client→server) and inbound (server→client) sides until you explicitly flush them.

```typescript
import { test, expect } from "bun:test";
import { createPoeTileTestHarness } from "poe-tiles-sdk/v1/test-utils.js";
import { myBackendConfig } from "../synced-store/backend-config";
import type { MySchema } from "../synced-store/schema";

const harness = createPoeTileTestHarness<MySchema>({
  store: { backendConfig: myBackendConfig },
});
const { store, transport } = await harness.createControlledClient();

// Initialize the client (complete the pull handshake)
await transport.flushUntil(store.waitForServerData());
```

`transport.flushUntil(store.waitForServerData())` is the standard way to initialize a controlled client before starting a scenario.

## Disabling and Enabling Auto-Flush

Toggle each direction independently:

```typescript
transport.outbound.disableAutoFlush();   // stop client→server
transport.inbound.disableAutoFlush();    // stop server→client
transport.outbound.enableAutoFlush();
transport.inbound.enableAutoFlush();
```

## Flushing Messages

| Method | Effect |
|--------|--------|
| `transport.outbound.flushNext()` | Send the next queued outbound message |
| `transport.inbound.flushOne()` | Deliver the next inbound message |
| `transport.inbound.flushAll()` | Deliver all queued inbound messages |
| `transport.step()` | One full round trip (outbound, then inbound) |
| `transport.flushUntil(promise)` | Keep flushing until a promise resolves |

## Optimistic-Update Test

Mutations apply locally before any network round trip. Verify the local state updates before anything is sent:

```typescript
test("optimistic updates visible immediately", async () => {
  const { store, transport } = await harness.createControlledClient();
  await transport.flushUntil(store.waitForServerData());

  transport.outbound.disableAutoFlush();

  await store.mutate.setValue({ key: "test", value: "optimistic" });

  // Value is readable locally, even though nothing has been sent
  const value = await store.query((tx) => tx.table("data").get("test"));
  expect(value).toBe("optimistic");

  harness.dispose();
});
```

## Protocol-Aware Queue Introspection

When you need to filter queued messages by their protocol type (e.g., `poke`, `push_response`, `pull_response`), use the protocol helpers:

```typescript
import { hasInboundType } from "poe-tiles-sdk/v1/test-utils.js";

// Check what's queued
const hasPoke = transport.inbound.queue.some(hasInboundType("poke"));

// Deliver only messages matching a predicate
await transport.inbound.flushMatching(hasInboundType("poke"));

// Remove a message from the queue without delivering it
transport.inbound.remove(hasInboundType("push_response"));
```

For reordering and failure simulation, see [testing-race-conditions.md](testing-race-conditions.md) and [testing-network-failures.md](testing-network-failures.md).
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