themis

Inspect runtime state via window.svelteRedux.reduxContext after Store.initDevTool() exposes an initialized Store instance. Multiple exposed stores produce a reduxContext array and a console.error. Use reducer tests for reference-equality diagnostics. Public Store API: @augmentcode/themis/svelte-store; devtools registration is package-internal implementation context.

Per-slice directory layout ({name}-types.ts, {name}-slice.ts, {name}-selectors.ts, sagas/{name}-saga.ts plus tests). Saga-only slices skip reducer registration. Register reducers in the Store constructor map; store.init() wires the Redux store and package saga manager but does NOT auto-start app sagas — start each one explicitly via store.runSaga(sagaFn). Do not manually register package @internal_ sagas. Ownership: exactly one {name}-slice.ts and one {name}-selectors.ts module per slice directory; split multiple slices into separate directories. Naming: {Feature}State, {feature}Reducer, camelCase slice identity keys/namespaces, verb-phrase actions, select* prefix, "sliceName/actionName" action types.

Root routing index for framework-independent Redux and redux-saga guidance in themis. Use for canonical Redux state policy, action/reducer primitives, normalized state helpers, typed-redux-saga patterns, saga manager behavior, saga channel/effect helpers, explicit store pruning, serialization, testing, debugging, and verifier handoff. Use the selected Store family skill for framework-specific Store selector/component behavior, choosing only one concrete Store family per app.

ReactStore component integration guidance for React app/root wiring. Covers where to create/configure ReactStore, init/dispose ownership, app saga startup with reactStore.runSaga(sagaFn), direct selector signal reads in JSX/TSX, Babel transform/useSignals tracking, selector .useValue(...args) fallbacks for hook/plain-value boundaries, and Store-first dispatch without Svelte or StreamingStore lifecycle rules.

React selector lifecycle and call-mode guidance. Maps direct calls that return Preact React signals as the preferred React consumer path, .useValue(...args) for necessary hook/plain-value fallback paths, Babel transform/useSignals tracking, .select(state, ...args) for handlers/tests/composition, .effect(...args) for sagas, and .withStore(...) for explicit binding without Svelte lifecycle rules.

ReactStore selector emission scheduling guidance. Use for Store-owned coalescing of preferred direct ReadonlySignal outputs and .useValue(...args) fallback reads, throttledSelectorFrequency tuning, package-private scheduler boundaries, and avoiding manual debounce/wrapper subscriptions or audit-log misuse.

Author ReactStore selectors whose direct calls return Preact React ReadonlySignal values and are the preferred React consumer integration path. Covers signal selector arguments, .value tracking via Babel transform or useSignals(), Store-bound creation, .useValue(...args) as a fallback for hook/plain-value boundaries, .withStore(reactStore), pure .select(state) composition/testing, and saga-only .effect() usage without importing React selector internals.

ReactStore routing index for React UI work in themis. Use for @augmentcode/themis/react-store, Preact React signals, Babel transform or useSignals() tracking, signal selector results, direct signal reads, selector .useValue(...args) only when hook/plain-value fallbacks are necessary, and React-specific component/lifecycle/scheduling/migration routing. Route shared Redux/redux-saga concepts to core, Svelte readable work to svelte, and Node/server/observable work to streaming. Never mix this concrete React Store family with Svelte Store or StreamingStore patterns in one app.

ReactStore import, initialization, disposal, and Store-runtime guidance for the React signal Store variant. Use for @augmentcode/themis/react-store, inherited runSaga/dispatch/state behavior, and contrast with Svelte-readable Store or StreamingStore without teaching those call modes.

Canonical first-time themis setup entry. Start here for greenfield app setup, choose exactly one concrete Store family before creating files, and adapt imports, selector call modes, lifecycle, saga startup, and verification to that family.

Repository root router for themis skills. Start here to choose ./svelte/SKILL.md only for frontend-facing Svelte/SvelteKit paths with concrete Svelte evidence, ./react/SKILL.md for React UI paths using ReactStore and Preact signals, ./streaming/SKILL.md for Node/server/workers/CLIs/test harnesses or no-UI code paths by default, and ./core/SKILL.md for shared Redux, redux-saga concepts, or explicit Redux store pruning requests. Use ./setup/SKILL.md for first-time app setup. Svelte, React, and Streaming Store app patterns are mutually exclusive choices for any single app.

Lifecycle guidance for StreamingStore selectors: selectors may be defined from the configured StreamingStore, but direct observable calls require init(); dispose() tears down the Store-owned stream state. Use this for stream observation timing, withStore(streamStore), and Svelte-readable contrast notes.

Author StreamingStore selectors whose direct calls return Kefir Observable values. Covers observable selector arguments, Store-bound creation, withStore(streamStore), pure .select(state) composition/testing, and saga .effect() usage without importing streaming selector internals.

Root routing index for StreamingStore and Kefir/observable selector guidance in themis. Use by default for Node/server environments, background workers, CLIs, test harnesses, apps or code paths without concrete UI evidence, and cases where selector direct calls should return Kefir streams. Route shared Redux/redux-saga work to core, React UI/signals work to react, and Svelte frontend/readable work to svelte only when Svelte/SvelteKit evidence exists. Never mix this concrete Streaming Store family with Store/readable, ReactStore/signal, or component patterns in one app.

StreamingStore import, initialization, disposal, and Store-runtime guidance for the Kefir/observable Store variant. Use for @augmentcode/themis/streaming-store, inherited runSaga/dispatch/state behavior, and contrast with Svelte-readable Store without teaching readable selector call modes.

store.createSelector((state, ...args) => value) is the public app-local selector creation tied to a configured Store. Generic/shared selector helpers should accept a configured Store rather than importing standalone creation utilities. Use collection utilities such as getItem/getItems inside Store-bound selectors for O(1) collection lookups; proxy tracking is internal to Store selectors. Selectors are composed via .select(state) — never by calling selectFoo() inside another selector. .select (one-shot) and .effect() (saga) are the escape hatches from the default readable-store call mode.

Svelte-readable routing index for frontend-facing themis work only when the touched code path has concrete Svelte/SvelteKit evidence. Use for Store component wiring, Svelte readable selector lifecycle, and migration touchpoints. Route React UI paths to ../react/SKILL.md, Node/server/no-UI paths to ../streaming/SKILL.md by default, and shared Redux/redux-saga concepts to ../core/SKILL.md. Never mix this concrete Svelte Store family with ReactStore/signals or StreamingStore/Kefir patterns in one app.

Store import, initialization, disposal, and Store-runtime guidance for the canonical Svelte-readable Store variant. Use for @augmentcode/themis/svelte-store, useInitStore/useRunSaga lifecycle helpers, inherited runSaga/dispatch/state behavior, and contrast with ReactStore or StreamingStore without teaching those call modes.

Concise agent rules for reacting to selector value changes from sagas. Use takeLatestFromSelector, takeEveryFromSelector, or takeLeadingFromSelector for continuous watchers; use createChannelFromSelector only for custom race, conditional, or timeout flows and close it in finally. For conceptual examples, link to docs/SAGAS.md.

Concise agent rules for waitFor(selector, argsTuple, predicate, timeoutMs?). Use when a saga must pause until a named selector reaches a predicate. It checks the current value first, subscribes through createChannelFromSelector, returns true on match and false on timeout, and closes the channel in finally.

Local-only maintainer skill for keeping themis observable Store skill guidance consistent across Svelte readable, React ReadonlySignal, and Streaming/Kefir Observable families. Use when behavior, docs, install routing, or verification touchpoints must be updated for every observable-style selector output family.

Normalized entity storage via Collection<T, K>: createCollection plus addItem, addItems, addItemAt, upsertItem, updateItem, replaceItem, removeItem, filterCollection, getItem, getItems, findItem, filterItems, and reference counting (increaseRefsCount, decreaseRefsCount, getRefsCount, addItemAndCountRef). All operations are immutable and return a new Collection (or the same reference on a no-op). Public API: @augmentcode/themis/utils/collections/collection-utils; docs: docs/COLLECTIONS.md.

Top-level architectural rules for themis. Redux owns all shared state and stores canonical facts only; components render and dispatch; side effects live in sagas; state must be structured-cloneable; arrays hold primitives only (use Collection<T,K> for entities); legacy family-local shared stores are deprecated — migrate to Redux on contact; slice types go in {slice-name}-types.ts so cross-process imports do not pull in reducers or saga code.

Which store modules components may import (actions, selectors, types, and the initialized Store instance for dispatch/one-shot reads) and which are forbidden (saga files, operation modules, reducer internals, collection utils). Component files must never import typed-redux-saga or redux-saga. Services/non-component TS may import actions and selectors; sagas may import anything inside the store directory.

App-local safe localStorage access from sagas. getLocalStorageItem / setLocalStorageItem / removeLocalStorageItem / getLocalStorageKeysWithPrefix (plus getLocalStorageJSON / setLocalStorageJSON) wrap window.localStorage in try/catch so quota and private-browsing errors cannot crash a saga. Covers the init-saga pattern (load defaults on startup, merge with persisted JSON) and the persistence- saga pattern (takeEvery on write actions → read selector → setLocalStorage- Item). These helpers are example/app-local utilities, not package exports. Never call window.localStorage directly from a saga or component.

createReducer<State>(initialState) returns a reducer whose .with(action, fn) chain-registers pure handlers and returns the same reducer (fluent builder — no .build() needed). The reducer is a function (state = initialState, action) that dispatches to the registered handler by action.type. Reducers must be pure and immutable — no side effects, no mutation, no Date.now(). Reducers update canonical state only and never maintain selector-derived fields. Return the same reference when nothing changes so selector reference-equality memoization and test ref-equality assertions pass. `.initialState` is exposed for tests.

Required vi.mock("typed-redux-saga") boilerplate mapping each effect to redux-saga/effects so redux-saga-test-plan can interpret them (the call mock MUST use Array.isArray to handle [context, method] tuple calls). Use expectSaga for integration (.withState / .put / .call / .provide / .dispatch / .silentRun) and testSaga for step-by-step (.next / .fork / .isDone). Reducer tests are pure — assert reference equality on no-op actions. State-integrity verification must prove derived values live in selectors and action/selector/saga owners are not duplicated. Source: docs/TESTING.md, ../SKILL.md §14.

Verifier quality gate for themis diffs. Hard-fails recurring review failures: instruction drift from required skills/docs, unjustified pass-through wrappers after refactors, duplicated utilities created without reuse discovery, non-canonical Redux state, and duplicate action/selector/saga owners. Use when reviewing or verifying changes to skills, docs, reducers, utilities, refactors, or shared-state implementation.

The three selector call modes and Store-first dispatch rule — the #1 source of runtime crashes in themis. Covers selectFoo() at component init (Svelte readable via getContext), selectFoo.select(state) for one-shot reads in event handlers / callbacks / async, yield* selectFoo.effect() inside sagas, and selectFoo.select(state) when composing selectors. Documents Store.dispatch usage, the lifecycle_outside_component crash, and the wrong-shape trap when passing the selector object to yield* select().

Public guidance for Store-owned selector emission coalescing and optional FPS tuning. Selector scheduler helpers are internal details and must not be imported from any public subpackage. Use Store-bound selectors directly; their readables are already cached, optimized, and scheduled by package internals. Do not add memoization, debounce/throttle, manual caches, or scheduler wrappers around Store-created selectors.

Agent guidance for the package-owned saga manager: crash tracking in manager status and serialized addCrash reports, per-saga cleanup with clearCrashes, internal crash report storage keyed by saga name with newest MAX_SAGA_CRASH_REPORTS retained, Store runSaga start/stop/restart behavior, and getBackOffDelay exponential backoff. Do not teach app code to import package-internal saga-manager files.

Hard rules for canonical Redux state and deduplicated ownership. Store only canonical state: no derived fields, no duplicated entity copies, no parallel arrays/maps for the same records, and no reducer-maintained selector outputs. Actions, selectors, and sagas must each have one canonical owner and one implementation. Includes preflight searches and verifier handoff evidence.

Preact Signals guidance for ReactStore React apps. Use for ReadonlySignal<T>, .value reads/writes, computed(), Babel transform or useSignals() tracking, direct signal JSX rendering, component-local useSignal/useComputed/useSignalEffect, and separating React signal consumption from Svelte readable or Streaming/Kefir patterns.

Concise agent rules for typed-redux-saga work in this package. Use for saga watchers/workers, canonical saga ownership, Store saga registration/startup, Store-first saga startup, cancellation-friendly debounce, retryWithTimeout, wrapStreamingGenerator, and routing to saga-manager crash/restart guidance. For conceptual API explanations and examples, link to docs/SAGAS.md instead of duplicating them.

createAction<[Params]>(type) produces action creators with positional-tuple payloads; an optional payloadModifier transforms args into any payload shape. createAsyncAction<[Args], SuccessPayload>(asyncType, stagesType) produces a request/success/failure triplet plus a promise on each request. Always namespace action types as "sliceName/actionName". Action creators expose .type and .toString, so they are passed directly to takeEvery/takeLatest — never .type. Async creators expose static .success/.failure creators on the creator itself, and per-instance success/failure/promise on each dispatched action. Each action type has one canonical owner; search for existing action creators before adding another.

createBooleanPreference({ sliceName, field, setActionName, toggleActionName }) emits a setAction (payload [value: boolean]) and a zero-argument toggleAction plus a .register(builder) helper that chains both handlers onto a createReducer builder. The field parameter is constrained to keys whose value type is boolean. Use it instead of hand-writing setX / toggleX pairs. Public API: @augmentcode/themis/utils/store/boolean-preference; related guidance: ../SKILL.md §11.

Generic EventChannel consumers for sagas. Use redux-saga takeEvery(channel, worker) for every-event consumption and takeLatest(channel, worker) for latest-only consumption. Own app-provided channel lifecycle explicitly and call channel.close() in a finally block on cancel / failure. Use these patterns for app-provided EventChannel factories, websocket, DOM-event, or IPC EventChannel consumers. Distinct from selector-channels — do NOT wrap a selector-derived channel in generic EventChannel consumers; use takeEveryFromSelector / takeLatestFromSelector instead.

State keyed by a domain id (workspace, project, tenant). State shape is { byDomainId: Record<string, T> }. createDomainScopedHelpers(emptyState) returns getDomainState, setDomainState, and clearDomainState — immutable helpers that read with an emptyState fallback, write per-domain entries, and drop domains (returning the same reference when the id was absent). Public API: @augmentcode/themis/utils/store/domain-scoped; related guidance: ../SKILL.md §10.

Generic redux-saga API reference for agents. Covers createSagaMiddleware, middleware.run, runSaga, Effect creators, effect combinators, watcher helpers, channel support, buffers, Task/Channel/Buffer/SagaMonitor interfaces, cancellation, context, blocking vs non-blocking semantics, and testing helpers.

Redux state must be structured-cloneable. Allowed: string, number, boolean, null, undefined, plain objects, arrays of primitives. Forbidden: Date, Map, Set, WeakMap, WeakSet, RegExp, Promise, Function, class instances, Error, Symbol. Alternatives: Date → number (ms), Map → Record<string, T>, Set → string[] or Record<string, true>, RegExp → string, Error → { message, stack }.