smartstate/readme.hints.md

# Smartstate Implementation Notes

## Current API (as of analysis)

### State Part Initialization
- State parts can be created with different init modes: 'soft', 'mandatory', 'force', 'persistent'
- Persistent mode automatically calls init() internally - no need to call it manually
- WebStore integration for persistent state uses IndexedDB

### Actions
- Actions are created with `createAction()` method
- Two ways to dispatch actions:
  1. `stateAction.trigger(payload)` - returns Promise<TStatePayload>
  2. `await statePart.dispatchAction(stateAction, payload)` - returns Promise<TStatePayload>
- Both methods now return the same Promise, providing flexibility in usage

### State Management Methods
- `select()` - returns Observable with startWith current state
- `waitUntilPresent()` - waits for specific state condition
- `stateSetup()` - async state initialization with cumulative defer
- `notifyChangeCumulative()` - defers notification to end of call stack (no callback parameter)

### State Hash Detection
- Uses SHA256 hash to detect actual state changes
- Bug: Currently stores the state object itself as hash instead of the actual hash
- This prevents proper duplicate notification prevention

### Type System
- Can use either enums or string literal types for state part names
- Test uses simple string types: `type TMyStateParts = 'testStatePart'`

## Fixed Issues in Documentation
1. Updated trigger() to return Promise (API enhancement)
2. Added dispatchAction as alternative method
3. Corrected notifyChangeCumulative usage
4. Clarified persistent mode auto-init
5. Added stateSetup documentation
6. Fixed state hash detection description
7. Both trigger() and dispatchAction() now return Promise for consistency