sim / rules

---
description: "Zustand store patterns and the workflow value state invariants"
globs: ["apps/sim/**/store.ts","apps/sim/**/stores/**/*.ts"]
---

<!-- Generated from .claude/rules/sim-stores.md by `bun run skills:sync`. Edit the source, not this file. -->

# Zustand Store Patterns

Stores live in `stores/`. Complex stores split into `store.ts` + `types.ts`.

## Basic Store

```typescript
import { create } from 'zustand'
import { devtools } from 'zustand/middleware'
import type { FeatureState } from '@/stores/<feature>/types'

const initialState = { items: [] as Item[], activeId: null as string | null }

export const useFeatureStore = create<FeatureState>()(
  devtools(
    (set, get) => ({
      ...initialState,
      setItems: (items) => set({ items }),
      addItem: (item) => set((state) => ({ items: [...state.items, item] })),
      reset: () => set(initialState),
    }),
    { name: 'feature-store' }
  )
)
```

## Persisted Store

```typescript
import { create } from 'zustand'
import { persist } from 'zustand/middleware'

export const useFeatureStore = create<FeatureState>()(
  persist(
    (set) => ({
      width: 300,
      setWidth: (width) => set({ width }),
      _hasHydrated: false,
      setHasHydrated: (v) => set({ _hasHydrated: v }),
    }),
    {
      name: 'feature-state',
      partialize: (state) => ({ width: state.width }),
      onRehydrateStorage: () => (state) => state?.setHasHydrated(true),
    }
  )
)
```

## Rules

1. Use `devtools` middleware (named stores)
2. Use `persist` only when data should survive reload
3. `persist` MUST use `partialize` with an explicit whitelist of the durable fields. Exclude transient flags (`isResizing`, drag/hover state) and `_hasHydrated` from the whitelist, and never spread the whole state (`{ ...state }`) — it leaks actions and transient state into storage
4. `_hasHydrated` pattern for persisted stores needing hydration tracking
5. Immutable updates only
6. `set((state) => ...)` when depending on previous state
7. Provide `reset()` action

## Outside React

```typescript
const items = useFeatureStore.getState().items
useFeatureStore.setState({ items: newItems })
```

## Workflow value state invariants

Workflow state is split across two stores on purpose: `useWorkflowStore` holds block
structure (plus a hydration-time copy of each subblock value) and `useSubBlockStore`
holds live values, so per-keystroke edits don't re-render the canvas. Rules that keep
this split correct:

- The structure's `subBlocks[*].value` is stale after any edit. Never read it directly
  for a current value — merge via `mergeSubblockState` (`@/stores/workflows/utils`,
  which reads the subblock store) or `mergeSubblockStateWithValues` (the single merge
  implementation, in `@sim/workflow-persistence/subblocks`), or read the subblock store. Exception: condition/router dynamic-handle subblocks dual-write the
  structure (`syncDynamicHandleSubblockValue`) and may be read from either source.
- Merge semantics are tri-state: a key present in the subblock store wins — including
  `null`, which means "explicitly cleared". Absent/`undefined` falls back to the
  structure. Do not add merge or precedence logic anywhere else; if a new reader needs
  different semantics, extend the shared merge.
- Every subblock-store write must go through `collaborativeSetSubblockValue` (or a
  batch equivalent) so the identical value is persisted via the realtime server. A
  store write that skips persistence makes the client's merged state diverge from the
  DB draft, which deploy snapshots — producing phantom "Update" states on the deploy
  button that clear on refresh. Hydration-derived local-only writes are allowed only
  when change detection compensates, and the exemption list in the store's own
  docstring (`workflows/subblock/store.ts`) is the record of which ones do and why —
  keep the two in step.
- Change detection compensates by resolving each subblock value to the configuration
  it represents (`lib/workflows/canonical/`), so a blank value and a value equal to
  the field's declared `defaultValue` compare equal. It does NOT compensate for a
  local-only write of a value the user could have chosen. If you cannot name the
  declared default your write matches, it is not exempt.
- Deploy materializes declared defaults into `webhook.providerConfig`, so anything
  reading a derived artifact back into the store is writing values the DB draft does
  not have. That circularity is the origin of this whole failure mode; prefer not
  reading derived artifacts back at all.

More agent context in simstudioai/sim

63 other files this repository gives its agents, the first 60 shown.