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\
frontend & backend?" -> "src/shared/" [label="yes"];
    "Used by both\
frontend & backend?" -> "Runs in\
Node.js only?" [label="no"];
    "Runs in\
Node.js only?" -> "IPC handler?" [label="yes"];
    "Runs in\
Node.js only?" -> "React component\
or hook?" [label="no"];
    "IPC handler?" -> "src/backend/handlers/" [label="yes"];
    "IPC handler?" -> "src/backend/services/" [label="no"];
    "React component\
or hook?" -> "src/frontend/components/" [label="component"];
    "React component\
or hook?" -> "src/frontend/hooks/" [label="hook"];
    "React component\
or 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\
component?" -> "Use query hooks" [label="yes"];
    "Inside React\
component?" -> "Use queryService\
singleton" [label="no\
(command, service)"];

    "Need to mutate\
file tree?" -> "queryService.mutations.*\
(optimistic updates)" [label="always"];
    "Need to read\
file content?" -> "readFileContent()\
helper (cache-first)" [label="preferred"];

    node [shape=box];
    "Use query hooks" [style=filled, fillcolor="#e8f5e9"];
    "Use queryService\
singleton" [style=filled, fillcolor="#e8f5e9"];
    "queryService.mutations.*\
(optimistic updates)" [style=filled, fillcolor="#fff3e0"];
    "readFileContent()\
helper (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

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
                 \x3C--transport push events--  \x3C--IPC--  ProjectManager \x3C-- 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