| name | fantasia-action-manager |
| description | Centralized renderer action manager: registry, sync FIFO queue, fire-and-forget async dispatch, unified error reporting (single console row + single toast), session-only action history, and the DialogActionMonitor surface. Use when adding or migrating user-meaningful UI actions, when a save/dialog needs consistent failure surfacing, or when working on the in-app action monitor. |
Fantasia Archive — action manager (faActionManager)
What exists today
- Registry:
types/I_faActionManagerDomain.ts (FA_ACTION_IDS, T_faActionId, I_faActionPayloadMap)
- Definitions:
faActionDefinitions.ts + handlers faActionDefinitionHandlers.ts; lookup findFaActionDefinition
- Run APIs:
faActionManagerRun.ts — runFaAction (fire-and-forget), runFaActionAwait → boolean
- Sync queue:
faActionManagerSyncQueue.ts — FIFO, FA_ACTION_SYNC_TIMEOUT_MS = 30_000, max 32, opt-in dedup, awaitSyncQueueDrain()
- Async: immediate dispatch; tracked in
S_FaActionManager.inFlightAsyncActions
- Error reporting:
faActionManagerErrorReporting_manager.ts — one console.error + one Notify.create per failure via reportFaActionFailure
- History:
faActionManagerHistory.ts — session ring (FA_ACTION_HISTORY_MAX = 500), snapshotActionHistory()
- Store:
S_FaActionManager.ts — mirrors runtime state; orchestration in actionManager/ scripts
- Bridge:
faActionManagerStoreBridge.ts — resolveFaActionManagerStore() boot/test safe
- DialogActionMonitor:
src/components/dialogs/DialogActionMonitor/ — snapshot on @show; story tags: ['skip-visual']
- Menu: Help / Info → Action Monitor →
runFaAction('openActionMonitorDialog')
Single-toast rule
Action manager = only error toasts for registered actions. Handlers throw or return false; stores must not emit duplicate negative Notify. Success toasts may stay in store when user-relevant.
saveProjectSettings: project name + optional worlds snapshot via faProjectWorldsPersistSnapshotFromDialog.
Migrated call sites (today)
- Async: dev tools, settings dialogs, markdown docs, saves, window chrome, language, Action Monitor, …
- Sync: close app, refresh after language change
- Keybinds:
faKeybindRunCommand.ts → FA_KEYBIND_COMMAND_TO_ACTION_ID → runFaAction
Adding a new action (checklist)
types/I_faActionManagerDomain.ts — append id + payload map entryfaActionDefinitionHandlers.ts + row in faActionDefinitions.ts (kind, optional dedup)- Call sites →
runFaAction / runFaActionAwait
- i18n: reuse
globalFunctionality.faActionManager.actionFailed template
- Tests:
src/scripts/actionManager/_tests/ + call site tests; keybind routes → faKeybindRunCommand tests
- Strip duplicate negative
Notify from handlers/stores
File map
- Domain:
types/I_faActionManagerDomain.ts
- Manager:
src/scripts/actionManager/ (definitions, run, queue, error reporting, history, store bridge)
- Store:
src/stores/S_FaActionManager.ts
- Monitor UI:
DialogActionMonitor/
- Menu:
AppControlMenus/_data/helpInfo.ts
- Keybinds:
faKeybindRunCommand.ts
- i18n:
L_faActionManager.ts, L_DialogActionMonitor.ts
Tests
Key suites: faActionDefinitions, faActionManagerRun, faActionManagerSyncQueue, faActionManagerHistory, faActionManagerErrorReporting*, faActionManagerStoreBridge, migrated call sites, DialogActionMonitor Vitest/Playwright, checkActionMonitor.playwright.spec.ts
Related
Types
Shared types → types/. See types-folder.mdc.
