state-stores
Builds and checks Zustand stores - factories, pure reducers, persist-then-publish, useShallow selectors, updateAndPublish, the GameSession reducer. Use when adding a store, action, selector or undo/continue logic, or on Maximum update depth. Not for the save file (save-persistence-and-migrations).
- License 许可
- MIT
- 最近更新
- 2026-11-05
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- state-stores
- description
- Builds and checks Zustand stores - factories, pure reducers, persist-then-publish, useShallow selectors, updateAndPublish, the GameSession reducer. Use when adding a store, action, selector or undo/continue logic, or on Maximum update depth. Not for the save file (save-persistence-and-migrations).
02 资源文件 96
- 资产文件assets/shared.json961 B
- 脚本examples/use-display-settings.ts1001 B
- 脚本examples/use-hint-button.ts1.8 KB
- 参考文档references/game-session.md11.1 KB
- 参考文档references/store-pattern.md16.7 KB
- 脚本scripts/check-lib.mjs44.4 KB
- 脚本scripts/check-reducers.mjs15.9 KB
- 脚本scripts/check-stores.mjs14.4 KB
- 脚本scripts/lib/app-modules.mjs3.1 KB
- 脚本scripts/lib/fixture-tree.mjs1.4 KB
- 脚本scripts/lib/source-scan.mjs3.5 KB
- 脚本scripts/selftest.mjs961 B
- 其他templates/packages/shell/src/app/stores-context.tsx1.6 KB
- 脚本templates/packages/shell/src/game-host/game-session-reducer.test.ts7.0 KB
- 脚本templates/packages/shell/src/game-host/game-session-reducer.ts4.5 KB
- 脚本templates/packages/shell/src/game-host/game-session-store.test.ts1.6 KB
- 脚本templates/packages/shell/src/game-host/game-session-store.ts2.3 KB
- 脚本templates/packages/shell/src/game-host/game-session-types.ts2.3 KB
- 脚本templates/packages/shell/src/game-host/run-writer.test.ts3.4 KB
- 脚本templates/packages/shell/src/game-host/run-writer.ts2.7 KB
- 脚本templates/packages/shell/src/game-host/saved-run.test.ts2.9 KB
- 脚本templates/packages/shell/src/game-host/saved-run.ts4.7 KB
- 脚本templates/packages/shell/src/stores/create-shell-stores.ts1.0 KB
- 脚本templates/packages/shell/src/stores/progress-reducer.test.ts4.3 KB
- 脚本templates/packages/shell/src/stores/progress-reducer.ts4.5 KB
- 脚本templates/packages/shell/src/stores/progress-selectors.test.ts1.6 KB
- 脚本templates/packages/shell/src/stores/progress-selectors.ts2.3 KB
- 其他templates/packages/shell/src/stores/progress-store.test.tsx4.0 KB
- 脚本templates/packages/shell/src/stores/progress-store.ts1.9 KB
- 脚本templates/packages/shell/src/stores/restart-store.test.ts2.9 KB
- 脚本templates/packages/shell/src/stores/restart-store.ts3.0 KB
- 脚本templates/packages/shell/src/stores/settings-reducer.test.ts4.6 KB
- 脚本templates/packages/shell/src/stores/settings-reducer.ts3.2 KB
- 脚本templates/packages/shell/src/stores/settings-selectors.test.ts2.0 KB
- 脚本templates/packages/shell/src/stores/settings-selectors.ts1.6 KB
- 脚本templates/packages/shell/src/stores/settings-store.test.ts3.2 KB
- 脚本templates/packages/shell/src/stores/settings-store.ts1.8 KB
- 脚本templates/packages/shell/src/stores/stats-reducer.test.ts649 B
- 脚本templates/packages/shell/src/stores/stats-reducer.ts1.1 KB
- 脚本templates/packages/shell/src/stores/stats-selectors.test.ts1.0 KB
- 脚本templates/packages/shell/src/stores/stats-selectors.ts625 B
- 脚本templates/packages/shell/src/stores/stats-store.test.ts2.0 KB
- 脚本templates/packages/shell/src/stores/stats-store.ts1.7 KB
- 脚本templates/packages/shell/src/stores/update-and-publish.test.ts1.7 KB
- 脚本templates/packages/shell/src/stores/update-and-publish.ts1.4 KB
- 脚本templates/packages/shell/src/testing/counter-game.ts1.5 KB
- 脚本templates/packages/shell/src/testing/create-test-save.ts2.4 KB
- 参考文档tests/fixtures/check-reducers/bad-best-overwritten/EXPECT.txt54 B
- 脚本tests/fixtures/check-reducers/bad-best-overwritten/packages/shell/src/stores/progress-reducer.ts4.2 KB
- 参考文档tests/fixtures/check-reducers/bad-continue-twice/EXPECT.txt37 B
- 脚本tests/fixtures/check-reducers/bad-continue-twice/packages/shell/src/game-host/game-session-reducer.ts4.5 KB
- 参考文档tests/fixtures/check-reducers/bad-hint-every-time/EXPECT.txt79 B
- 脚本tests/fixtures/check-reducers/bad-hint-every-time/packages/shell/src/stores/progress-reducer.ts4.4 KB
- 参考文档tests/fixtures/check-reducers/bad-hint-ignores-config/EXPECT.txt77 B
- 脚本tests/fixtures/check-reducers/bad-hint-ignores-config/packages/shell/src/stores/progress-reducer.ts4.6 KB
- 参考文档tests/fixtures/check-reducers/bad-mutating/EXPECT.txt51 B
- 脚本tests/fixtures/check-reducers/bad-mutating/packages/shell/src/stores/settings-reducer.ts2.7 KB
- 参考文档tests/fixtures/check-reducers/bad-paused-moves/EXPECT.txt35 B
- 脚本tests/fixtures/check-reducers/bad-paused-moves/packages/shell/src/game-host/game-session-reducer.ts4.5 KB
- 参考文档tests/fixtures/check-reducers/bad-take-back-keeps-move/EXPECT.txt77 B
- 脚本tests/fixtures/check-reducers/bad-take-back-keeps-move/packages/shell/src/game-host/game-session-reducer.ts4.3 KB
- 参考文档tests/fixtures/check-reducers/bad-undo-unlimited/EXPECT.txt71 B
- 脚本tests/fixtures/check-reducers/bad-undo-unlimited/packages/shell/src/game-host/game-session-reducer.ts4.5 KB
- 参考文档tests/fixtures/check-reducers/bad-volume-unclamped/EXPECT.txt59 B
- 脚本tests/fixtures/check-reducers/bad-volume-unclamped/packages/shell/src/stores/settings-reducer.ts2.7 KB
- 参考文档tests/fixtures/check-reducers/good/README.md405 B
- 参考文档tests/fixtures/check-stores/bad-action-name/EXPECT.txt63 B
- 脚本tests/fixtures/check-stores/bad-action-name/packages/shell/src/stores/settings-reducer.ts2.7 KB
- 参考文档tests/fixtures/check-stores/bad-created-twice/EXPECT.txt102 B
- 其他tests/fixtures/check-stores/bad-created-twice/packages/shell/src/app/create-shell-app.tsx380 B
- 参考文档tests/fixtures/check-stores/bad-direct-sql/EXPECT.txt42 B
- 脚本tests/fixtures/check-stores/bad-direct-sql/packages/shell/src/game-host/game-session-store.ts190 B
- 参考文档tests/fixtures/check-stores/bad-impure-reducer/EXPECT.txt55 B
- 脚本tests/fixtures/check-stores/bad-impure-reducer/packages/shell/src/stores/progress-reducer.ts4.4 KB
- 参考文档tests/fixtures/check-stores/bad-no-selector/EXPECT.txt38 B
- 脚本tests/fixtures/check-stores/bad-no-selector/packages/shell/src/screens/settings/use-theme-row.ts182 B
- 参考文档tests/fixtures/check-stores/bad-object-selector/EXPECT.txt81 B
- 脚本tests/fixtures/check-stores/bad-object-selector/packages/shell/src/screens/levels/use-pack-header.ts647 B
- 参考文档tests/fixtures/check-stores/bad-publish-first/EXPECT.txt82 B
- 脚本tests/fixtures/check-stores/bad-publish-first/packages/shell/src/stores/progress-store.ts1.8 KB
- 参考文档tests/fixtures/check-stores/bad-run-end-no-publish/EXPECT.txt84 B
- 脚本tests/fixtures/check-stores/bad-run-end-no-publish/packages/shell/src/game-host/record-run-end.ts662 B
- 参考文档tests/fixtures/check-stores/bad-run-end-recipe-variable/EXPECT.txt84 B
- 脚本tests/fixtures/check-stores/bad-run-end-recipe-variable/packages/shell/src/game-host/record-run-end.ts782 B
- 参考文档tests/fixtures/check-stores/bad-second-persistence/EXPECT.txt82 B
- 脚本tests/fixtures/check-stores/bad-second-persistence/packages/shell/src/stores/progress-store.ts167 B
- 参考文档tests/fixtures/check-stores/bad-shallow-v4/EXPECT.txt28 B
- 脚本tests/fixtures/check-stores/bad-shallow-v4/packages/shell/src/game-host/use-score.ts349 B
- 参考文档tests/fixtures/check-stores/bad-singleton/EXPECT.txt38 B
- 脚本tests/fixtures/check-stores/bad-singleton/packages/shell/src/stores/settings-store.ts282 B
- 参考文档tests/fixtures/check-stores/bad-untested-reducer/EXPECT.txt65 B
- 参考文档tests/fixtures/check-stores/bad-untested-reducer/REMOVE.txt48 B
- 脚本tests/fixtures/check-stores/good/.claude/skills/demo/planted-store.ts128 B
- 脚本tests/fixtures/check-stores/good/apps/demo/ios/Generated/planted-store.ts143 B
- 参考文档tests/fixtures/check-stores/good/README.md426 B
- 脚本tests/fixtures/check-stores/good/skills/demo-skill/tests/fixtures/bad-singleton/packages/shell/src/stores/planted-store.ts169 B
03 SKILL.md 正文
State stores
App state lives in four thin Zustand 5 stores over pure reducers, created from the loaded save document; a run lives in a pure GameSession changed by one reducer. Every change is reduced, saved, then published, and two scripts prove it.
Rules that must hold
- One store per domain (settings, progress, stats, premium), made by a
create<Domain>Store(save)factory and created once increateShellStores(save). No module-level stores and nocreatefromzustand: tests need fresh stores per test, and a direction reload re-runs module code. Beside themcreateShellStoresmakes the one store that is never saved,restart(createRestartStore()instores/restart-store.ts): the direction reload a screen has started, held from the tap until the reload so the route guards keep that screen (a pending reload must never outlive the reload, so it has no save section and no reducer). - Every
dispatchreduces, persists, then publishes:next = reducer(get(), action); if the reducer can return the same object (a refused or no-op action), stop there;save.update(recipe)with only this store's sections; thenset(...)fromsave.doc()(nevernext). The screen never shows a value that is not on disk, a failed write publishes nothing, and a rejected document never reaches the store, where it would spoil every later write. - All logic sits in pure reducers with imperative kebab-case actions (
set-theme,record-level-result,use-free-hint,reset-statistics). Reducers import no runtime code, never mutate, never readDateor randomness; "today" arrives in the action. Pure reducers are tested without React and replay the same everywhere. - A selector returns a primitive or a reference already in the state. One that builds an object or array is wrapped in
useShallowfromzustand/shallow; no store hook is called without a selector. In Zustand 5 a new reference per call loops ("Maximum update depth exceeded"), and the v4 equality argument is gone. - A write that spans sections (run end, "Reset all progress", debug import) is ONE
updateAndPublish(save, stores, { recipe, refreshBackup: true }): one validatedsave.update, then every section store re-reads the document. Several dispatches would be several transactions (a kill between them leaves stars without statistics), and a baresave.updateleaves the stores showing old numbers until a restart. - A run is a
GameSessionchanged only bygameSessionReducer, in a per-run store whose persist callback runs before publish. The board animates only what is already saved, so a kill mid-animation loses nothing. - The save document is the only persistence. No
zustand/middlewarepersist, AsyncStorage or MMKV; stores and the game host never import SQLite or the save store, they callsave.update. One document means one version number and tested migrations. - Every reducer has a test file next to it, and every persisting store a thin persist-before-publish test. The rules of the product (best result kept, one free hint a day, one continue per run) are only safe while a test pins them.
Workflow
-
Read references/store-pattern.md: the domains table, the pattern, action names, selectors, cross-section writes, tests and every checker rule. Read references/game-session.md before touching a run, undo, continue, hints or the saved run.
-
Check the prerequisites in the app repo: the save layer (
SaveService,createFakeSaveStore,planLoad, the schema inservices/save/),ClockPort(services/clock/clock-port.tswithnowMs,todayandmsUntilNextLocalDay;TEST_CLOCKintesting/create-test-save.tsimplements all three) and the Premium store (stores/premium/premium-store.ts). If the save layer or the clock port is missing, build it first (save-persistence-and-migrations ships both); the stores are hydrated fromsave.doc(). -
New Shell (Shell step 5 of the build order, where the stores and the GameSession store land with the services, so check-stores passes from step 5 on): first install Zustand into the Shell package, exactly this pinned line from the repo root (the dependency policy's plan for
zustand; the repo's.npmrcsetssave-exact=true, so npm writes the exact version):npm install zustand@5.0.15 -w packages/shellEvery store template imports
zustand, so without ittscfails withTS2307: Cannot find module 'zustand'. Then copytemplates/packages/shell/src/intopackages/shell/src/(stores,app/stores-context.tsx, game host, testing helpers). The settings files are the same files the settings work uses; keep them identical. WirecreateShellStores(hydrated.save)into the composition root and<StoresProvider>. -
New action: write the failing reducer test first (one example per action, a fast-check property for ranges and idempotence), add the union member and the reducer case, and name it by rule 3. The store's
dispatchstays generic. -
New read in a component or hook: pick or add a selector in
<domain>-selectors.ts; a value built per call goes throughuseShallow(see examples/use-display-settings.ts and examples/use-hint-button.ts). -
Cross-section change: compose the pure section functions in one recipe and call
updateAndPublish(save, stores, { recipe, refreshBackup: true }). -
Run logic: copy the
game-host/templates, create the run store withcreateRunWriter(save, game.persistence)as its persist callback, restore a saved run withrestoreRun(it comes back paused), and add the game's two property tests (undo k moves; replay reproduces the snapshot). The run end is not a run-store write: the composition root gives the game hostwriteRunEnd: (write) => updateAndPublish(save, stores, write)(rule 5; the game-host-integration skill wires it). -
Run the tests:
npx jest packages/shell/src/stores packages/shell/src/game-host --ci --selectProjects unit --coverage --collectCoverageFrom='packages/shell/src/stores/**/*.ts' --coverageThreshold='{}'(paths first; onlynpm run test:coveragejudges the thresholds) andnpx tsc -p packages/shell --noEmit. -
Run the checks from the repo root:
node ${CLAUDE_SKILL_DIR}/scripts/check-reducers.mjs .andnode ${CLAUDE_SKILL_DIR}/scripts/check-stores.mjs .. Fix everyFAILline (each names file, rule and fix) and rerun until both printRESULT: PASS.
Definition of done
- [ ]
ShellStoresholds settings, progress, stats, premium and the unsavedrestartstore; onlycreateShellStorescalls the store factories. - [ ] Each
dispatchwrites only its own sections throughsave.update, then callsset; a reducer that returns the same object (refused action) causes no write. - [ ] Every action name is an imperative kebab-case verb; time is passed in actions.
- [ ] Every selector call returns a primitive or state reference, or goes through
useShallow. - [ ] Run end and "Reset all progress" use one
updateAndPublishwrite with the backup refreshed, never a baresave.update. - [ ] Reducer, store, session, saved-run and run-writer tests pass, and
tscis clean. - [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-reducers.mjs .printsRESULT: PASS - [ ]
node ${CLAUDE_SKILL_DIR}/scripts/check-stores.mjs .printsRESULT: PASS
Anti-patterns
export const useThing = create(...). A singleton hook-store shares state across tests and app starts; write a factory and add it tocreateShellStores.set(next)and thensave.update(...), or asetTimeout"debounced save". The screen then shows unsaved data, and a kill loses it; persist first, synchronously.useProgressStore((s) => ({ stars: s.x, best: s.y })). A new object every render loops forever in Zustand 5; wrap it inuseShallowor select two primitives.useSettingsStore()to "get everything". It re-renders on every change; select what the component shows.- Recording a finished run with three dispatches (progress, stats, daily), or with
save.update(applyRunEnd…)alone. Use oneupdateAndPublishrecipe so the result screen appears only after everything is on disk and every store shows it. Date.now()ornew Date()in a reducer. PasstodayfromClockPortin the action; reducers must replay identically.- Event-style action names (
hint-used,themeChanged). Name the command:use-hint,set-theme. - Mutating
pastorlogwithpush. Spread into new arrays;check-reducersfreezes the input to catch it. - Keeping undo history on disk. Save the move log and snapshot; rebuild
pastby replay on restore. - A bare
npm install zustand(or@latest, or a caret range). It floats to whatever is newest, can be younger than the 7-day release age, and breaks the one-version pin; run exactlynpm install zustand@5.0.15 -w packages/shellfrom the repo root.
Files in this skill
| File | What it is | Read/run when |
|---|---|---|
| references/store-pattern.md | Domains, the reduce-persist-publish pattern, actions, reducers, cross-section writes, selectors and useShallow, Premium store, tests, checker rules | Workflow step 1, and on any store change |
| references/game-session.md | GameSession types, what each action does, run store, when the run is written, saved run restore, game property tests | Workflow steps 1 and 7 |
templates/packages/shell/src/stores/ |
settings-*, progress-*, stats-* reducers, selectors, stores and tests; create-shell-stores.ts; update-and-publish.ts (+ test); restart-store.ts (+ test: the unsaved restart store) |
Workflow steps 3 to 6 |
templates/packages/shell/src/app/stores-context.tsx |
ShellStores, StoresProvider, useStores |
Workflow step 3 |
templates/packages/shell/src/game-host/ |
Session types, reducer, per-run store, saved run, run writer, and their tests | Workflow step 7 |
templates/packages/shell/src/testing/ |
create-test-save.ts (boot-like in-memory save) and counter-game.ts (tiny rules for session tests) |
Workflow steps 4 and 7 |
| examples/use-display-settings.ts | A hook with one primitive selector and one useShallow object selector |
Workflow step 5 |
| examples/use-hint-button.ts | A hook reading three stores and dispatching only from a handler | Workflow step 5 |
scripts/check-stores.mjs |
Static checker: factories, persist order, purity, action names, selectors, useShallow, second persistence, SQLite bypass, cross-section writes | Workflow step 9, and at the end |
scripts/check-reducers.mjs |
Runs the app's settings, progress and session reducers against their rules | Workflow step 9, and at the end |
scripts/lib/source-scan.mjs |
Call and selector scanning helpers for check-stores | Never by hand |
scripts/lib/app-modules.mjs |
Imports the app's TypeScript modules (Node type stripping, @e07/* resolution) |
Never by hand |
scripts/lib/fixture-tree.mjs |
Builds the self-test trees (templates plus one planted bug) | Never by hand |
scripts/selftest.mjs |
Proves both checkers pass the templates and catch every planted bug | After changing a checker or a template |
scripts/check-lib.mjs |
Shared script helper, synced from the library (do not edit here) | Never by hand |
assets/shared.json |
Declares the shared files this skill copies in (check-lib.mjs and the six settings-* store files, synced from the library and identical to settings-and-preferences' copies: edit them there, never here) |
When adding a shared file |
tests/fixtures/ |
Planted-bug overlays (bad-*/ with EXPECT.txt) for both checkers |
When adding a checker rule |
Related skills
save-persistence-and-migrations- the SaveService, document schema and SQLite the stores write through.settings-and-preferences- the settings fields, S11 rows and the effect of each setting.daily-and-statistics- the daily and statistics maths and the run-end recipe.game-host-integration- mounting a game, HUD, pause and result flow around the run store.premium-purchase- the Premium store and its service.react-components-and-hooks- component rules for the hooks that read stores.tdd-workflow- the test-first loop for every reducer change.
04 同仓库更多 Skills
unit-and-component-tests
Sets up Jest and writes Pocket Arcade test code - three projects, RNTL 14 async via renderWithShell, root SDK mocks, fakes, fast-check, coverage, Stryker. Use when a test needs the Shell wrapper, a mock or a fake, or Jest fails. Not for the red-green loop (tdd-workflow) or goldens (golden-tests).
typescript-and-lint-rules
Enforces Pocket Arcade's strict TypeScript 6 tsconfigs, ESLint 9 flat config, Prettier and size limits. Use when writing or splitting .ts/.tsx or fixing a tsc or lint error. Not for gate wiring (quality-gates), names (naming-conventions) or import zones (architecture-and-boundaries).
demo-skill
Builds a demo. Use when testing the pitfall checker.
demo-skill
Builds a demo. Use when testing the pitfall checker.
troubleshooting-playbook
Diagnoses and fixes Pocket Arcade failures with a catalogue of 300+ known ones (symptom, cause, fix). Use when something errors, crashes, hangs or renders wrong, or an error or log needs explaining. Not for gate setup (quality-gates) or running builds (ios-simulator-build, ios-release-testflight).
toybox-visual-parity
Proves a built Pocket Arcade screen matches its Toybox design screenshot (light/dark, en/fa) and drives the fixes: capture, element gates, sheets, sign-off. Use when any screen is built or changed, or for visual parity, design match, screenshot compare. Not for building screens (toybox-screens).