Fable Developer

---

name: fable-dev description: > Use when working on the Fable codebase — modifying, debugging, or extending any part of the Electron + React creative writing app. Covers architecture, coding conventions, procedural recipes, and navigation guidance. Also use when asking questions about how Fable works internally or when planning a new feature.

---

Fable Development Guide

Fable is a creative-writing desktop app: Electron + React 19 + Vite + TanStack Query + Plate.js frontend, Node.js + SQLite + custom indexed filesystem backend, Google ADK for AI features.

Critical Invariant

Every file can have children, not just folders. FileNode.children exists on ANY node regardless of category. A text document can contain child documents (chapters containing scenes). Never assume only folders have children.

parentId and siblingIndex are computed by buildFileTree() at runtime — never persist them.

Where Does My Code Go?

digraph code_placement {
    rankdir=TB;
    node [shape=diamond];
    "Used by both\nfrontend & backend?" -> "src/shared/" [label="yes"];
    "Used by both\nfrontend & backend?" -> "Runs in\nNode.js only?" [label="no"];
    "Runs in\nNode.js only?" -> "IPC handler?" [label="yes"];
    "Runs in\nNode.js only?" -> "React component\nor hook?" [label="no"];
    "IPC handler?" -> "src/backend/handlers/" [label="yes"];
    "IPC handler?" -> "src/backend/services/" [label="no"];
    "React component\nor hook?" -> "src/frontend/components/" [label="component"];
    "React component\nor hook?" -> "src/frontend/hooks/" [label="hook"];
    "React component\nor hook?" -> "src/frontend/services/" [label="service/singleton"];
    node [shape=box];
    "src/shared/" [style=filled, fillcolor="#e8f5e9"];
    "src/backend/handlers/" [style=filled, fillcolor="#e3f2fd"];
    "src/backend/services/" [style=filled, fillcolor="#e3f2fd"];
    "src/frontend/components/" [style=filled, fillcolor="#fff3e0"];
    "src/frontend/hooks/" [style=filled, fillcolor="#fff3e0"];
    "src/frontend/services/" [style=filled, fillcolor="#fff3e0"];
}

Shared code constraint: src/shared/ must NOT import browser APIs, Node.js APIs, or React.

How Do I Access / Mutate Data?

digraph data_access {
    rankdir=TB;
    node [shape=diamond];
    "Inside React\ncomponent?" -> "Use query hooks" [label="yes"];
    "Inside React\ncomponent?" -> "Use queryService\nsingleton" [label="no\n(command, service)"];
    "Need to mutate\nfile tree?" -> "queryService.mutations.*\n(optimistic updates)" [label="always"];
    "Need to read\nfile content?" -> "readFileContent()\nhelper (cache-first)" [label="preferred"];
    node [shape=box];
    "Use query hooks" [style=filled, fillcolor="#e8f5e9"];
    "Use queryService\nsingleton" [style=filled, fillcolor="#e8f5e9"];
    "queryService.mutations.*\n(optimistic updates)" [style=filled, fillcolor="#fff3e0"];
    "readFileContent()\nhelper (cache-first)" [style=filled, fillcolor="#fff3e0"];
}

Never call window.api.* directly for tree mutations — always go through queryService.mutations.* which handles optimistic updates and rollback.

Key Directories

| Directory | What to find | |---|---| | src/types.ts | All shared types (FileNode, FileMetadata, ChatSession, Agent, etc.) | | src/shared/ | Code shared by both processes (graph, agentFlow, toolDescriptors, search) | | src/backend/handlers/ | IPC handlers: file, project, agent, agentFlow | | src/backend/services/ | IndexedFsService, UserDataService, ReferenceIndexService, agent/ | | src/backend/services/agent/ | AI system: AdkRunner, ToolFactory, providers, ChatDatabaseService | | src/frontend/components/ | All React components (chat/, graph/, fileViewer/, collectionViewer/) | | src/frontend/services/commandInfra/ | VS Code-style commands, keybindings, context keys | | src/frontend/services/query/ | TanStack Query: queryService, mutations, treeTransformations | | src/frontend/hooks/ | Custom hooks: useFileTree, useChat, useAgentFlowRun, etc. | | src/frontend/styles/plate/ | Plate.js editor plugins and kits | | src/locales/{en,zh-CN}/ | i18n translations (8 namespaces) | | e2e/ | Playwright E2E tests | | electron/preload.ts | IPC bridge — window.api.* definitions | | src/global.d.ts | TypeScript declarations for Window.api |

Common Task Recipes

Read references/recipes.md for detailed step-by-step procedures including:

Adding a new IPC channel (5-step checklist)

Adding a new command (5-step checklist)

Adding a new file subType (8-step checklist)

Adding a new agent tool (6-step checklist)

Adding a new sidebar panel or editor handler

Adding i18n strings

Architecture at a Glance

Read references/architecture.md for the full breakdown. Key mental model:

Frontend (React) --window.api.*--> Preload --IPC--> Backend handlers --> Services --> Disk
                 <--transport push events--  <--IPC--  ProjectManager <-- IndexedFsService events

State: TanStack Query is single source of truth. staleTime: Infinity everywhere.

File tree: Event-driven push from backend, never polled. useFileTree sets up listener.

Mutations: createTreeMutation factory: optimistic update -> IPC call -> rollback on error.

Commands: VS Code-style CommandService + ContextService + KeybindingService.

Editor routing: ContentViewer dispatches by subType first, then category.

AI: Google ADK with multi-provider LLM registry. See references/agent-system.md.

i18n Checklist

8 namespaces: common, fileExplorer, chat, project, editor, agentBuilder, graph, agentDefinition

In components: const { t } = useTranslation("namespace")

Outside React: import i18n from "@/src/i18n/i18n"; i18n.t("ns:key")

Always add keys to BOTH en and zh-CN

Build, Lint & Test

npm run dev:electron     # Dev mode (Vite + Electron)
npm run build            # Production build
npm run check            # Lint + format + TypeScript check
npm run test:e2e         # Playwright E2E tests (headless)
npm run test:e2e:headed  # E2E with visible browser

Path alias: @/* maps to repo root

Formatting: Prettier (double quotes, 4-space indent, semicolons)

Always run E2E tests you wrote before committing

Pitfalls

1. Any node can have children — not just folders 2. parentId/siblingIndex are derived — never persist 3. Tree mutations must be pure — treeTransformations.ts returns new arrays, never mutate 4. Always add i18n to BOTH locales — en and zh-CN 5. Toolbar renders via portal — #file-toolbar-portal in TopBar, not inside editor DOM 6. Input elements suppress keybindings — useKeybindings checks event.target tag 7. subType controls routing — checked before category in ContentViewer 8. Binary files use base64 over IPC — text uses UTF-8 9. STRUCTURAL_FILE_CHANGES control broadcasts — content "update" does NOT re-push tree 10. Add Window.api types — update src/global.d.ts when adding IPC channels 11. Shared code is process-agnostic — src/shared/ cannot import browser or Node APIs 12. Tool descriptors are shared — toolDescriptors.ts serves both UI commands and LLM agents 13. Every user-facing data element needs a tooltip

References

| Reference | Use when | |---|---| | references/architecture.md | Understanding layers, IPC channels, backend services, frontend providers | | references/command-system.md | Working with commands, keybindings, context keys, when clauses | | references/workspace-structure.md | On-disk file layout, metadata schema, storage guidelines | | references/agent-system.md | AI features: providers, streaming, tools, planning mode, chat persistence | | references/recipes.md | Step-by-step procedures for common development tasks |