Skip to content

file-map.md

Latest commit

 

History

History
486 lines (459 loc) · 36.2 KB

file-map.md

File metadata and controls

486 lines (459 loc) · 36.2 KB

File Map and Responsibilities

Note for agents: each time you are asked to update the documentation, if you found a ts or tsx file not specified here, you have to add it.

Mandatory doc navigation for new chats: start with docs/START-HERE.md — it provides the full bootstrap sequence and routes to all other docs.

Root-level project files

  • package.json
    • Scripts for dev/build/test/smoke.
    • Electron entry configured via main.
  • vite.config.ts
    • Preact plugin and Vitest config.
  • postcss.config.js
    • Tailwind PostCSS plugin.
  • tsconfig.electron.json
    • Compiles main/preload/shared contracts to dist-electron.

Electron layer

  • electron/main.ts
    • App lifecycle and BrowserWindow creation.
    • Wires smoke hooks and editor context-menu helpers.
    • Emits native fullscreen state changes to renderer.
    • Registers IPC handlers.
  • electron/window-config.ts
    • BrowserWindow security-related defaults.
  • electron/main-process/context-menu.ts
    • Native editor context menu: flat workspace commands (toggle split, toggle fullscreen, toggle focus mode) dispatched to renderer via WORKSPACE_CONTEXT_MENU_EVENT.
    • Includes the Paste Markdown menu entry for editable contexts; the menu dispatches { type: 'paste-markdown' } to the renderer when selected.
  • electron/main-process/smoke-hooks.ts
    • Startup smoke hooks.
  • electron/main-process/window-close.ts
    • Window close handler: intercepts close event, checks cached dirty state, shows native save dialog, and calls win.destroy() to force close.
  • electron/ipc.ts
    • Thin IPC registration/orchestration.
  • electron/ipc/spellcheck.ts
    • Spellcheck IPC handlers: reads and applies Electron session spellchecker settings for renderer settings UI, including normalized responses used by optimistic renderer updates.
  • electron/ipc-runtime.ts
    • Active project/index runtime state + watcher lifecycle.
  • electron/ipc-errors.ts
    • Shared IPC error envelope helper.
  • electron/preload.cts
    • Typed window.tramaApi bridge.
    • Includes fullscreen command and fullscreen-change subscription bridge.

IPC handlers

  • electron/ipc/handlers/ping-handler.ts
    • Ping endpoint.
  • electron/ipc/handlers/project-handlers/project-open-handler.ts
    • Open project + scan + reconcile + watcher start.
  • electron/ipc/handlers/project-handlers/project-folder-dialog-handler.ts
    • Native folder picker endpoint.
    • Enforces required project folders (book, lore, outline) by prompting to create missing folders or reselect another directory.
  • electron/ipc/handlers/project-handlers/document-handlers.ts
    • Read/save/create/rename/delete document + create folder handlers.
  • electron/ipc/handlers/project-handlers/folder-handlers.ts
    • Folder rename handler with subtree internal-write tagging and index/tag reconcile.
  • electron/ipc/handlers/project-handlers/index-handler.ts
    • Get index handler.
  • electron/ipc/handlers/project-handlers/order-handlers.ts
    • File reorder handler (handleReorderFiles) for drag-and-drop reorder in sidebar.
  • electron/ipc/handlers/ai-handlers.ts
    • AI import/export handlers: preview import, execute import, and backend export formatting endpoint.
  • electron/ipc/handlers/book-export-handler.ts
    • Book export handler: validates request payload and delegates multi-format book export to service with consistent error envelopes.
  • electron/ipc/handlers/zulu-handlers.ts
    • ZuluPad import handlers: opens native file picker for .zulu files, previews parsed pages, and executes multi-file import with configurable tag generation.

Services

  • electron/services/project-scanner.ts
    • Recursive markdown scan + tree data (including empty folders).
  • electron/services/document-repository.ts
    • Read/save/create/rename/delete markdown files + folder rename/create.
    • Persists markdown images to project-local res/*.png files on save and resolves them back to embedded data URLs on read.
  • electron/services/document-image-persistence.ts
    • Repository helper for markdown image persistence: rewrites embedded images to res/*.png, rehydrates local image links back to embedded PNG data URLs, and collects associated image paths for delete flows.
  • electron/services/frontmatter.ts
    • YAML frontmatter parse/serialize.
  • electron/services/index-service.ts
    • .trama.index.json load/save/reconcile.
    • Architecture: docs/architecture/project-index-architecture.md.
  • electron/services/watcher-service.ts
    • Chokidar wrapper + internal/external write classification.
  • electron/services/ai-import-service.ts
    • Parses AI clipboard blocks, builds preview metadata, and executes multi-file import writes.
  • electron/services/ai-export-service.ts
    • Formats selected files into === ARCHIVO: ... === blocks, validates relative paths against project root, and supports frontmatter include/exclude mode.
  • electron/services/zulu-import-service.ts
    • ZuluPad import service: parses .zulu XML content into pages, generates frontmatter with optional tags, and writes markdown files to the target folder.
  • electron/services/book-export-service.ts
    • Book export orchestrator: scans book/, builds ordered chapter models, sanitizes per format, dispatches renderer (md/html/docx/epub/pdf), and writes output artifact.
  • electron/services/book-export-image-source-transform.ts
    • Shared markdown image-source rewriting helpers: converts local image references to embedded data URLs during chapter build and rewrites sources to EPUB-compatible file:// URLs when packaging.
  • electron/services/book-export-order.ts
    • Book export ordering logic: derives base order from tree and applies per-folder corkboardOrder from index with stable fallback.
  • electron/services/book-export-sanitize.ts
    • Book export sanitize pipeline: strips frontmatter for all formats, strips HTML comments only for markdown output, and normalizes line endings/trailing whitespace.
  • electron/services/book-export-directives.ts
    • Shared directive parsing helpers for trama:center, trama:spacer, and trama:pagebreak, including canonical comment tokens and HTML artifact variants.
  • electron/services/book-export-pdf-fonts.ts
    • PDF font loading strategy: registers @pdf-lib/fontkit, resolves Unicode-capable system serif fonts, and falls back to standard fonts.
  • electron/services/book-export-pdf-inline.ts
    • PDF inline text helpers: markdown inline tokenization (**bold**/__bold__), line wrapping, and width measurement for mixed regular/bold runs.
  • electron/services/book-export-pdf-font-utils.ts
    • Font normalization utilities: normalizeForFont, safeTextForFont, normalizeRunsForFonts. Shared between PDF rendering functions.
  • electron/services/book-export-pdf-utils.ts
    • Core PDF writer implementation: createPdfWriter, PdfWriter interface, PdfLayoutState, and all drawing functions (drawRuns, drawHeading, drawPdfImage, etc.)
  • electron/services/book-export-pdf-renderer.ts
    • Re-export barrel for PDF book rendering. Exports PdfWriter, PdfLayoutState types and renderPdfBook, createPdfWriter from book-export-pdf-utils.ts. Uses pdf-lib with pagination, directive-aware spacing/page breaks, wrapped inline formatting, and chapter boundary page management.
    • Uses Unicode-capable system serif fonts when available (fallback to standard fonts).
  • docs/architecture/book-export-architecture.md
    • Canonical reference for the book export pipeline. Explains the file layout, PDF render pipeline, data models, directive mapping, image handling, page metrics, and test coverage.
  • docs/architecture/ai-import-export-architecture.md
    • AI import/export clipboard pipeline. Covers format grammar, import preview/execute flow, export formatting, path validation, IPC contract, and test coverage.

Renderer layer

  • src/app.tsx
    • Top-level app composition.
  • src/spellcheck/use-spellcheck-settings.ts
    • Renderer hook for spellcheck preferences: boot-time sync against Electron session, local persistence, enable/disable, language updates, and optimistic UI updates with rollback on IPC failure.
  • src/features/project-editor/use-project-editor.ts
    • Main feature hook (state + effects + action integration).
  • src/features/project-editor/project-editor-view.tsx
    • Screen-level composition (sidebar + editor + status).
  • src/features/project-editor/project-editor-dialogs.tsx
    • Centralized overlay/dialog composition for AI import/export and markdown book export modals plus toast notifications.
  • src/features/project-editor/use-project-editor-ui-actions.ts
    • Composes UI actions.
    • updateEditorValue(value, pane?) supports pane-targeted updates; split-pane call sites should pass explicit pane.
    • revertChanges(pane?) — Discards unsaved changes and reloads the file from disk. Reuses loadDocument under the hood.
  • src/features/project-editor/use-project-editor-focus-actions.ts
    • Fullscreen/focus-mode action hooks. When enabling focus, auto-collapses the sidebar.
  • src/features/project-editor/use-project-editor-file-actions.ts
    • Rename/delete file actions.
    • For file delete, forwards the optional deleteAssociatedImages choice to IPC.
  • src/features/project-editor/project-editor-image-save.ts
    • Renderer-side save helper that converts any non-PNG embedded image data URLs into PNG data URLs before persistence, matching the res/*.png storage contract.
  • src/features/project-editor/use-project-editor-folder-actions.ts
    • Folder rename action with dirty-subtree guard and split-layout remap before project reopen.
  • src/features/project-editor/project-editor-folder-logic.ts
    • Pure helpers for folder-prefix path remap (isPathInsideFolder, remapFolderPrefix, layout remap).
  • src/features/project-editor/project-editor-logic.ts
    • Pure workspace helpers: deriveActivePaneDocument (active pane projection), canSelectFile, reconcileWorkspaceLayout, buildConflictCopyPath, and layout persistence.
  • src/features/project-editor/use-project-editor-ui-actions-helpers.ts
    • Helper hooks for editor view actions: useSelectFileAction, useRevertChangesAction (calls loadDocument when pane is dirty, discarding unsaved changes), useEditorViewActions, useWorkspaceLayoutActions.
  • src/features/project-editor/use-project-editor-create-actions.ts
    • Create article/category actions.
  • src/features/project-editor/use-project-editor-sidebar-actions.ts
    • Sidebar UI actions. Blocks sidebar expand while focus mode is active.
  • src/features/project-editor/use-project-editor-layout-actions.ts
    • Workspace split and pane activation actions.
  • src/features/project-editor/use-project-editor-open-project.ts
    • Open-project flow and pane/layout reconciliation.
  • src/features/project-editor/use-project-editor-fullscreen-effect.ts
    • Renderer subscription to native fullscreen state changes.
  • src/features/project-editor/use-project-editor-shortcuts-effect.ts
    • Global workspace shortcuts (split/fullscreen/focus/pane switch).
  • src/features/project-editor/use-project-editor-close-effect.ts
    • Notifies dirty state to main process via notifyCloseState IPC and exposes window.__tramaSaveAll for the close handler to invoke saves before closing.
  • src/features/project-editor/use-workspace-layout-state.ts
    • Persist workspace layout (trama.workspace.layout.v1).
  • docs/architecture/split-pane-coordination.md
    • Canonical reference for the split pane per-pane state model. Documents the two-layer state model (layout vs document), all 7 formal contracts, state projection map, and key implementation files.
  • src/features/project-editor/use-sidebar-ui-state.ts
    • Persist sidebar UI (trama.sidebar.ui.v1).
  • src/features/project-editor/use-ai-import.ts
    • Renderer hook for AI import dialog state and calls to preview/execute import IPC actions.
  • src/features/project-editor/use-ai-export.ts
    • Renderer hook for AI export dialog state, IPC export call, and clipboard copy flow.
  • src/features/project-editor/use-book-export.ts
    • Renderer hook for book export dialog state: selected format, optional metadata (title/author), default output path handling, IPC export call, and success toast flow.
  • src/features/project-editor/use-zulu-import.ts
    • Renderer hook for ZuluPad import dialog state: file selection, preview, and execution via IPC.

Project editor hooks (detailed)

  • src/features/project-editor/use-project-editor-state.ts
    • Core local state for the editor feature (panes, loading/saving flags, conflict state, status messages).
    • Derives active editor state (selectedPath / editorValue / isDirty) from workspaceLayout.activePane.
    • Returns 6 memoized sub-states (documentState, paneState, layoutState, sidebarState, projectState, uiState) alongside the legacy values object for granular dependency tracking in action hooks.
  • src/features/project-editor/use-project-editor-sub-state-hooks.ts
    • Memoized sub-state builders extracted from useProjectEditorState to prevent false re-render cascades.
    • Exports useDocumentState, usePaneState, useLayoutState, useSidebarSt, useProjectSt, useUiSt, and getVisibleSidebarPaths.
  • src/features/project-editor/use-project-editor-actions.ts
    • Composes UI actions and core operations (load/save/open/clear) and wires them into the state.
    • Receives paneWorkspace from useProjectEditor.
  • src/features/project-editor/use-project-editor-autosave-effect.ts
    • Minimal Preact adapter: detects dirty → calls paneWorkspace.scheduleAutosave, detects clean/unmount → calls paneWorkspace.cancelAutosave. Timer logic lives in PaneWorkspace.
  • src/features/project-editor/pane/
    • Private module for pane coordination. All pane state, flush, save, and autosave access goes through this module.
    • pane/index.ts — barrel exporting PaneWorkspace, usePaneWorkspace, and public types
    • pane/pane-workspace.ts — coordinator class with read methods (getPaneDocument, isPaneDirty) and write methods (savePaneIfDirty, saveAllDirtyPanes, scheduleAutosave, updatePaneContent, etc.); markPaneSaved is private
    • pane/use-pane-workspace.ts — factory hook that encapsulates Preact setter injection, creating a PaneWorkspace instance via useMemo
    • pane/pane-save-logic.ts — executePaneSave (internal, not exported from barrel)
  • src/features/project-editor/use-project-editor-external-events-effect.ts
    • Subscribes to external file events (watcher) and handles reloads/conflicts/tree refresh.
  • src/features/project-editor/use-project-editor-context-menu-effect.ts
    • Handles workspace-level context menu commands (split/fullscreen/focus/split ratio).
  • src/features/project-editor/use-project-editor-fullscreen-effect.ts
    • Listens for native fullscreen changes and mirrors them into UI state.
  • src/features/project-editor/use-project-editor-shortcuts-effect.ts
    • Global keyboard shortcuts handling for editor workspace actions.
  • src/features/project-editor/use-project-editor-open-project.ts
    • Orchestrates opening a project: load snapshot, reconcile layout, preload inactive pane.
  • src/features/project-editor/use-project-editor-ui-actions.ts
    • High-level UI action builders used by components (pick folder, select file, save, create, rename, delete, focus/fullscreen toggles).
  • src/features/project-editor/use-project-editor-create-actions.ts
    • Helpers to create new articles and category folders in the project.
  • src/features/project-editor/use-project-editor-file-actions.ts
    • File operations (rename, delete) with status updates and project reopen flows.
  • src/features/project-editor/use-project-editor-conflict-actions.ts
    • Actions to resolve external edit conflicts (reload, keep, save-as-copy, compare).
  • src/features/project-editor/use-project-editor-layout-actions.ts
    • Workspace layout actions (assign file to pane, toggle split, set ratio, switch active pane).
  • src/features/project-editor/use-project-editor-focus-actions.ts
    • Focus-mode controls (enable/disable, set scope: line/sentence/paragraph). Auto-collapses sidebar on focus enable.

Editor workspace components

  • src/features/project-editor/components/workspace-editor-panels.tsx
    • Single/split editor rendering and pane interactions.
    • Split-pane dirty routing source of truth: each pane editor must route onChange to its own pane (updateEditorValue(..., pane)).
  • src/features/project-editor/components/editor-panel.tsx
    • Editor panel shell, sync labels, save affordance.
  • src/features/project-editor/components/ai-import-dialog.tsx
    • Modal dialog for AI import text input, mode selector (replace / append), preview trigger, and import confirmation.
  • src/features/project-editor/components/ai-import-preview-section.tsx
    • Preview summary/list for parsed import files (new vs existing).
  • src/features/project-editor/components/ai-export-dialog.tsx
    • Export dialog controller (portal, close behavior, keyboard handling) wired to export hook actions.
  • src/features/project-editor/components/ai-export-dialog-body.tsx
    • Export dialog UI body with multi-select file list, include-frontmatter option, and export/cancel actions.
  • src/features/project-editor/components/book-export-dialog.tsx
    • Markdown book export modal controller (portal, close behavior, keyboard handling).
  • src/features/project-editor/components/book-export-dialog-body.tsx
    • Book export dialog body with project root display, optional metadata inputs, output path input, and export/cancel actions.
  • src/features/project-editor/components/zulu-import-dialog.tsx
    • Modal dialog for ZuluPad file import: file selection trigger, target folder input, tag mode selector, preview state, and import execution portal.
  • src/features/project-editor/components/zulu-import-dialog-body.tsx
    • ZuluPad import dialog body: file info display, folder/tag configuration form, actions row, and preview/execute sub-components.
  • src/features/project-editor/components/rich-markdown-editor.tsx
    • Quill-based rich Markdown editor component (lifecycle, toolbar integration, focus-mode hookup).
  • src/features/project-editor/components/rich-markdown-editor-core.ts
    • Core editor lifecycle and sync logic (initialize Quill, apply markdown, enable/disable, register typography handlers).
    • Also listens for workspace paste-markdown commands and handles reading/parsing clipboard Markdown and inserting HTML into Quill.
  • src/features/project-editor/components/rich-markdown-editor-external-sync.ts
    • External-value sync hook: compares canonical values via normalizeEditorDocumentValue + areEquivalentEditorValues, preserves Quill selection, manages isApplyingExternalValueRef flag.
  • src/features/project-editor/components/rich-markdown-editor-serialization.ts
    • Editor debounced serialization session: registers text-change listener, manages debounce timer and flush lifecycle, and hydrates image placeholders before forwarding to parent state via onChange.
  • src/features/project-editor/components/rich-markdown-editor-value-sync.ts
    • Canonical editor-value helpers: normalize image-bearing markdown into placeholder form and compare equivalent external/editor values without triggering destructive re-renders.
  • src/features/project-editor/components/rich-markdown-editor-layout-blots.ts
    • Registers Quill BlockEmbed-based layout directive blots (center, spacer, pagebreak, unknown) so directive objects survive Quill canonicalization.
  • src/features/project-editor/components/rich-markdown-editor-layout-clipboard.ts
    • Adds clipboard matcher logic that maps directive artifact nodes into embed Delta ops consumed by layout directive blots.
  • src/features/project-editor/components/rich-markdown-editor-layout-keyboard.ts
    • Registers explicit ArrowLeft/ArrowRight keyboard bindings so pagebreak embeds are traversed atomically in one cursor step.
  • src/features/project-editor/components/rich-markdown-editor-layout-actions.ts
    • Toolbar-triggered insertion helpers for center boundaries, spacer directives, and pagebreak directives.
  • src/features/project-editor/components/rich-markdown-editor-layout-centering.ts
    • Synchronizes centered styling for editor blocks located between center:start and center:end boundary artifacts.
  • src/features/project-editor/components/rich-markdown-editor-commands.ts
    • Handles workspace context-menu commands (paste-markdown, copy-as-markdown) and clipboard serialization/paste flow for the rich editor.
  • src/features/project-editor/components/rich-markdown-editor-find.tsx
    • In-document find hook: Ctrl/Cmd+F (find) and Ctrl/Cmd+H (find+replace) activation, query/match state, replace actions, and integration between floating UI and editor selection.
  • src/features/project-editor/components/rich-markdown-editor-find-state.ts
    • Shared find/replace state helpers: search state hook (useSearchState), replace actions hook (useReplaceActions), Quill text helpers, and keyboard modifier detection.
  • src/features/project-editor/components/rich-markdown-editor-find-overlay.tsx
    • Floating find bar UI (find input, replace input, counter, prev/next, replace, replace all, close, toggle-replace) plus active-match overlay rendering.
  • src/features/project-editor/components/rich-markdown-editor-find-visual.ts
    • Active-match visual sync helpers: computes Quill bounds and keeps highlighted match visible while preserving input focus.
    • Includes focus-mode-aware centering via handleFocusModeMatch().
  • src/features/project-editor/components/rich-markdown-editor-typography.ts
    • Smart typography auto-replacement on user input: -- → —, << → «, >> → ». Each substitution is isolated as its own Ctrl+Z undo entry via history.cutoff().
  • src/features/project-editor/components/rich-markdown-editor-focus-scope.ts
    • Focus-mode hook orchestration: applies emphasis classes and wires scroll centering, selection tracking, and listener setup.
    • Coordinates between focus scope helpers and centered scroll updates.
  • src/features/project-editor/components/rich-markdown-editor-focus-scope-helpers.ts
    • Focus scope helper functions: applies/clears CSS class emphasis, manages CSS Highlights API, handles fallback text emphasis.
    • Contains getSelectionViewportRect() for real DOM viewport geometry of the current selection.
  • src/features/project-editor/components/rich-markdown-editor-focus-scope-scroll.ts
    • Centered scroll logic: computes target scroll position to keep active line centered vertically.
    • Uses requestAnimationFrame phases to recalculate after padding changes; expands top/bottom edge space dynamically.
  • src/features/project-editor/components/rich-markdown-editor-focus-scope-geometry.ts
    • Geometry helpers for focus-mode (text offset resolution, visual line/sentence boundary calculations).
  • src/features/project-editor/components/rich-markdown-editor-toolbar.ts
    • Injects and synchronizes toolbar controls (save button, revert button, sync indicator) into the Quill toolbar.

Sidebar components

  • src/features/project-editor/components/sidebar/sidebar-panel.tsx
    • Sidebar shell/orchestrator.
  • src/features/project-editor/components/sidebar/sidebar-panel-body.tsx
    • Active section body composition. Thin adapter that converts raw sidebar callback strings through sidebar-path-scoping.ts before invoking project-level actions.
  • src/features/project-editor/components/sidebar/sidebar-panel-logic.ts
    • Section scoping + filter-state helpers. Delegates path branding/scoping to sidebar-path-scoping.ts.
  • src/features/project-editor/components/sidebar/sidebar-path-scoping.ts
    • Canonical sidebar path-scoping module. Owns branded path types (SectionRelativePath, ProjectRelativePath, SidebarSectionRoot) and all conversions between section-relative/project-relative paths, reorder payload scoping, and create-path building.
  • src/features/project-editor/components/sidebar/sidebar-rail.tsx
    • Section rail and collapse toggle.
  • src/features/project-editor/components/sidebar/sidebar-explorer-content.tsx
    • Explorer container and dialog orchestration.
  • src/features/project-editor/components/sidebar/sidebar-explorer-body.tsx
    • Explorer body (path, filter, tree, state hints, menus/dialogs).
  • src/features/project-editor/components/sidebar/sidebar-tree.tsx
    • Interactive tree rows, keyboard nav, right-click file hook, and drag-and-drop reorder state. Drag handler logic lives in use-sidebar-tree-drag-handlers.ts.
  • src/features/project-editor/components/sidebar/sidebar-tree-logic.ts
    • Pure tree build/flatten helpers.
  • src/features/project-editor/components/sidebar/sidebar-tree-sort.ts
    • sortTreeRowsByOrder() — reorders sidebar tree rows by corkboardOrder from index. Re-exported via sidebar-tree-logic.ts.
  • docs/architecture/sidebar-drag-drop-architecture.md
    • Comprehensive reference for sidebar drag-and-drop architecture: drop position model, data flow for reorder vs move, path scoping rules, IPC contracts, component hierarchy, and Slice 1 implementation details.
  • src/features/project-editor/components/sidebar/sidebar-tree-row-button.tsx
    • Individual tree row with drag handle, drag event handlers, and drop-indicator CSS classes (is-drop-before, is-drop-after, is-drop-onFolder).
  • src/features/project-editor/components/sidebar/drop-indicator.tsx
    • Drop indicator position type model (before | after | onFolder | onSection). Visual rendering is handled by CSS classes on SidebarTreeRowButton.
  • src/features/project-editor/components/sidebar/use-sidebar-tree-expanded-folders.ts
    • Expanded folder state management, including rename remap consumption via sidebar folder-rename events.
  • src/features/project-editor/components/sidebar/use-sidebar-tree-drag-handlers.ts
    • Drag-and-drop handler logic (dragStart, dragOver, drop) and drop position calculation, extracted from sidebar-tree.tsx.
  • src/features/project-editor/components/sidebar/sidebar-file-drop-logic.ts
    • Pure helpers for file drop handling: cross-folder move + reorder (handleFileCrossFolderDrop) and same-folder reorder (handleFileSameFolderReorder).
  • src/features/project-editor/components/sidebar/sidebar-folder-rename-events.ts
    • One-shot folder rename event bridge used to remap expanded folder state after refresh.
  • src/features/project-editor/components/sidebar/sidebar-filter.tsx
    • Filter input UI.
  • src/features/project-editor/components/sidebar/use-sidebar-filter-shortcut.ts
    • Legacy sidebar filter shortcut helper (Ctrl/Cmd+F), currently not wired after in-document find shortcut reassignment.
  • src/features/project-editor/components/sidebar/use-sidebar-responsive-collapse.ts
    • Auto-collapse on narrow viewport.
  • src/features/project-editor/components/sidebar/sidebar-create-dialog.tsx
    • Create modal dialog.
  • src/features/project-editor/components/sidebar/use-sidebar-create-dialog.ts
    • Create modal state logic.
  • src/features/project-editor/components/sidebar/sidebar-file-context-menu.tsx
    • Right-click file action menu.
  • src/features/project-editor/components/sidebar/use-sidebar-file-context-menu.ts
    • Context menu state/handlers.
  • src/features/project-editor/components/sidebar/sidebar-folder-context-menu.tsx
    • Right-click folder action menu (rename in V1).
  • src/features/project-editor/components/sidebar/use-sidebar-folder-context-menu.ts
    • Folder context-menu state/handlers.
  • src/features/project-editor/components/sidebar/sidebar-file-actions-dialog.tsx
    • Rename/delete confirmation/input dialog.
    • File delete dialog optionally offers deleting linked res/*.png images.
  • src/features/project-editor/components/sidebar/use-sidebar-file-actions-dialog.ts
    • Rename/delete dialog state.
    • Loads linked image info before file delete confirmation so the user can choose whether associated images are removed.
  • src/features/project-editor/components/sidebar/sidebar-folder-actions-dialog.tsx
    • Folder rename input dialog.
  • src/features/project-editor/components/sidebar/use-sidebar-folder-actions-dialog.ts
    • Folder rename dialog state.
  • src/features/project-editor/components/sidebar/sidebar-footer-actions.tsx
    • Create buttons (+Article, +Category).
  • src/features/project-editor/components/sidebar/sidebar-settings-content.tsx
    • Sidebar settings panel (width slider, theme/focus controls, and spellcheck settings UI).
  • src/features/project-editor/components/sidebar/sidebar-settings-subcomponents.tsx
    • Split-out sub-components for settings: theme preference buttons, focus scope select, spellcheck language select, spellcheck controls, panel width control.
  • src/features/project-editor/components/sidebar/theme-setting.tsx
    • Theme settings section (theme preference buttons with resolved theme display).
  • src/features/project-editor/components/sidebar/spellcheck-setting.tsx
    • Spellcheck settings section (spellcheck controls wrapper).
  • src/features/project-editor/components/sidebar/focus-scope-setting.tsx
    • Focus scope settings section (focus scope select wrapper).
  • src/features/project-editor/components/sidebar/panel-width-setting.tsx
    • Panel width settings section (panel width control wrapper).
  • src/features/project-editor/components/sidebar/sidebar-transfer-content.tsx
    • Transfer section composition: separate Project interchange (AI import/export) and Book export blocks with format selector + export trigger.

Shared contracts

  • src/shared/ipc.ts
    • IPC channel constants, Zod schemas, shared envelope/types.
  • src/shared/project-sections.ts
    • Single source of truth for relevant project sections (book, outline, lore).
    • Exports RELEVANT_SECTION_NAMES, RELEVANT_SECTION_ROOTS and isRelevantPath() helper.
  • src/shared/workspace-context-menu.ts
    • Event bridge contract between Electron context menu and the renderer: WORKSPACE_CONTEXT_MENU_EVENT constant and WorkspaceContextCommand union type.
    • The WorkspaceContextCommand includes the { type: 'paste-markdown' } case used by the native menu and editor listeners.
  • src/shared/markdown-layout-directives.ts
    • Shared parser/serializer helpers for invisible markdown layout directives (center, spacer, pagebreak) and editor artifact mapping.
  • src/shared/markdown-layout-directives-artifact-node.ts
    • Artifact-node serializer for converting directive blot/artifact DOM nodes back into canonical markdown comments.
  • src/shared/markdown-layout-directives-spacing.ts
    • Markdown post-serialization normalization that converts repeated blank-line runs into canonical trama:spacer directives.
  • src/shared/zulu-parser.ts
    • .zulu XML parser: extracts page titles and content from ZuluPad document format.
  • src/types/trama-api.d.ts
    • Global declaration for window.tramaApi.

Tests

Core and regression suites:

  • tests/ipc-contract.test.ts
  • tests/fullscreen-ipc.test.ts
  • tests/use-project-editor.test.ts
  • tests/workspace-layout-persistence.test.ts
  • tests/project-editor-conflict-flow.test.ts
  • tests/project-editor-logic.test.ts
  • tests/project-folder-dialog-handler.test.ts
  • tests/rich-markdown-editor.test.ts
  • tests/rich-markdown-editor-tag-overlay.test.ts
  • tests/paste-markdown.test.ts
  • tests/focus-mode-scope.test.ts
  • tests/rich-markdown-editor-focus-rendering.test.ts
    • CSS Highlights API priority, fallback overlay, scope change marker behavior.
  • tests/rich-markdown-editor-focus-split-pane.test.ts
    • Split pane focus regression: active/inactive pane behavior, isActive strict equality (=== false), CSS class application for .is-focus-mode-inactive dimming.
  • tests/sidebar-tree.test.ts
  • tests/sidebar-path-scoping-types.test.ts
    • Runtime smoke coverage for the new path-scoping seam plus compile-time brand assertions enforced through tests/typescript-compile.test.ts.
  • tests/sidebar-filter.test.ts
  • tests/sidebar-panels.test.ts
  • tests/spellcheck-settings.test.ts
  • tests/sidebar-scroll-regression.test.ts
  • tests/workspace-keyboard-shortcuts.test.ts
  • tests/frontmatter-parser.test.ts
  • tests/index-reconciliation.test.ts
  • tests/theme-preference.test.ts
  • tests/startup-smoke.test.ts
  • tests/electron-smoke.test.ts
  • tests/typescript-compile.test.ts
  • tests/ai-import-parser.test.ts
    • Parser coverage for === ARCHIVO: ... === clipboard format and edge cases.
  • tests/ai-export-service.test.ts
    • Export formatter service coverage (multi-file output, frontmatter toggle, path hardening, missing file behavior).
  • tests/ai-export-ipc-handler.test.ts
    • IPC envelope validation for export handler success/error payload paths.
  • tests/book-export-ipc-handler.test.ts
    • Book export IPC coverage: payload validation, markdown export success, phase C format exports (html/docx/epub/pdf), and failure envelope behavior.
  • tests/book-export-order.test.ts
    • Book export order coverage: base tree ordering, index override, and non-book path filtering.
  • tests/book-export-sanitize.test.ts
    • Book export sanitize coverage: frontmatter/tag removal, markdown-only comment stripping, and whitespace normalization.
  • tests/book-export-renderers.test.ts
    • Renderer coverage for markdown/html/docx/epub/pdf outputs, including directive conversion and binary artifact generation.
  • tests/book-export-image-utils.test.ts
    • Image utility coverage: PNG/JPEG dimension parsing from bytes, DOCX proportional size calculation, and markdown reference-style image extraction.
  • tests/use-ai-export.test.ts
    • Renderer export hook coverage for IPC call shape, clipboard copy, and error state handling.
  • tests/folder-rename-repository.test.ts
    • Repository-level folder rename coverage (success + validation/collision failures).
  • tests/folder-rename-ipc-handler.test.ts
    • IPC folder rename envelope coverage and on-disk subtree move assertions.
  • tests/project-editor-folder-logic.test.ts
    • Pure path-remap coverage for folder rename in split-layout state.
  • tests/order-handlers.test.ts
    • IPC handler coverage for handleReorderFiles (saves order to index, handles empty folder path, rejects no-active-project, rejects invalid payload).
  • tests/drag-drop-sidebar.test.ts
    • Sidebar drag-drop logic coverage (folder vs file drop targets, before/after position reorder logic, tree row filtering).
  • tests/markdown-layout-directives.test.ts
    • Unit coverage for directive extraction, warning behavior, artifact rendering, and canonical serialization helpers.
  • tests/ai-import-service.test.ts
    • Import service coverage: replace mode overwrites existing file content, append mode appends with separator, preview correctly classifies new vs existing files.
  • tests/ai-import-ipc-handler.test.ts
    • IPC handler coverage: rejects invalid importMode with VALIDATION_ERROR, append mode produces expected written content via IPC.
  • tests/pane-workspace.test.ts
    • Unit tests for PaneWorkspace coordinator class: mutation methods (updatePaneContent, loadPaneDocument, clearPanes, updatePaneMeta), save/isDirty contracts, autosave timer lifecycle.
  • tests/use-pane-workspace.test.ts
    • Unit tests for the usePaneWorkspace factory hook: stable identity across re-renders, proper passing of bindings/refs/saveFn to PaneWorkspace.
  • tests/use-ai-import.test.ts
    • Renderer import hook coverage: importMode forwarded to preview IPC call, importMode forwarded to execute IPC call, log message format matches created/appended/replaced/skipped/errors counts.
  • tests/window-close.test.ts
    • Regression tests for window close behavior: dirty state IPC notification, __tramaSaveAll global function, parallel save of dirty panes.
  • tests/rich-markdown-editor-value-sync.test.ts
    • Unit coverage for canonical editor-value normalization and equivalence between base64 markdown images and IMAGE_PLACEHOLDER markdown.

Architecture docs

  • docs/architecture/rich-editor-hotspots.md
    • Fast routing document for the editor's fragile seams: debounce, external sync, pane persistence, layout-vs-document state, focus geometry, and command bridge.
  • docs/architecture/window-close-architecture.md
    • Documents the window close architecture: main-process close handler, renderer dirty-state notification via IPC, __tramaSaveAll bridge, promise-chain cancel pattern, and key files.
  • docs/architecture/zulu-import-architecture.md
    • Canonical reference for the ZuluPad import pipeline. Explains parser logic, encoding detection, tag generation, line ending normalization, IPC contract, file map, and UI flow.

Build outputs

  • dist/ -> renderer build.
  • dist-electron/ -> transpiled Electron and shared runtime files.
  • Required preload artifact: dist-electron/electron/preload.cjs.