garethpaul/poe-games-procedural-dungeons / .claude/skills/synced-store
synced-store
VerifiedBuild 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/actions.md
View on GitHub<!-- owner: jyoung-q -->
# Actions
Actions are server-only operations. Use them when you need things mutators can't do: AI calls, external APIs, randomness, or accessing server-only data.
| | Mutator | Action |
|---|---------|--------|
| Runs on | Client + Server | Server only |
| Instant UI update | Yes (optimistic) | No (waits for server) |
| Use when | Client has all data needed | Needs AI, external APIs, or server-only data |
## Declaring Actions in the Schema
```typescript
import { TILE_SCHEMA_VERSION } from "./tile-schema-version";
const schema = defineSchema({
schemaVersion: TILE_SCHEMA_VERSION,
tables: { /* ... */ },
mutators: { /* ... */ },
actions: {
generateWithAI: {
description: "Generate todo text from a prompt using AI",
input: z.object({ id: z.string(), prompt: z.string() }),
output: z.object({ text: z.string() }),
},
},
});
```
Actions are also exposed as MCP tools, so AI models can call them directly.
## Implementing Actions in the Backend Config
```typescript
export const todoBackendConfig = defineBackendConfig<typeof todoSchema>({
schema: todoSchema,
mutators: { /* ... */ },
actions: {
generateWithAI: async (ctx, input) => {
const stream = await ctx.platform.call("poe.botStream.open", {
botName: "GPT-4o-mini",
queryRequest: {
version: "1.0",
type: "query",
query: [{ role: "user", content: input.prompt }],
user_id: "",
conversation_id: crypto.randomUUID(),
message_id: crypto.randomUUID(),
},
});
const generatedText = await readBotStreamText(stream);
await ctx.mutate("setTodo", {
id: input.id,
text: generatedText,
status: "generating",
});
await ctx.mutate("setTodo", {
id: input.id,
text: generatedText,
status: "ready",
});
return { text: generatedText };
},
},
});
```
## Calling Actions from the Client
```typescript
const result = await store.action.generateWithAI({
id: "todo-1",
prompt: "What should I cook for dinner?",
});
```
## Enqueuing Actions from Mutators
Mutators can trigger actions as a side effect. `ctx.enqueueAction()` is a no-op on the client; on the server it runs the action after the mutation commits. Call it unconditionally — no `ctx.isServer` guard needed.
```typescript
mutators: {
createAndGenerate: async (ctx, input) => {
// Instant: create a placeholder todo
await ctx.table("todos").set({
itemKey: input.id,
value: { id: input.id, text: "Generating...", completed: false, status: "generating" },
});
// Queued: server will run this after the mutation commits
ctx.enqueueAction("generateWithAI", {
id: input.id,
prompt: input.prompt,
});
},
},
```
## When NOT to use an Action
- Data changes that the client can compute — use a mutator (optimistic, no round trip).
- Secrets the client should never see — use `serverOnly()` tables; an action can expose a derived result.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |