# LyricFlow Advanced Features

This document provides a deep dive into the specialized features that make LyricFlow a unique tool for lyricists.

### LyricDown Syntax Guide

LyricFlow introduces **LyricDown**, a Markdown-like syntax for lyricists, natively saved as `.lmd` files. This custom syntax helps you structure your creative process without interfering with phonetic analysis.

| Element | Syntax | Usage |
| :--- | :--- | :--- |
| **Header** | `# Text` | Titles, large section breaks. |
| **Metadata** | `@Key: Value` | Track BPM, Key, Artist, or mood info. |
| **Comment** | `> Text` | Personal notes, alternative line ideas. |
| **Tag** | `[Tag]` | Structural markers (Verse, Chorus, Bridge). |

### The `.lmd` Format
LyricFlow uses the **.lmd (Lyric Markdown)** extension as its native format. While standard `.txt` files are supported, using `.lmd` ensures that your projects are clearly identified as LyricDown documents.

### Strict Analysis Filtering
The Rhyme Engine is context-aware. It **ignores** Headers, Metadata, and Comments entirely. When you click a word inside a comment or header, **the sidebar suggestions will not trigger**(may not function properly.), keeping your workspace clutter-free.

## 2. IDE Workspace & Layout

LyricFlow implements a professional "three-pane" architecture:

-   **Project Explorer (Left)**: A full-featured file system explorer. Supporting right-click operations (New File/Folder, Rename, Delete) and `.lyricproject` session loading.
-   **Tabbed Editor (Center)**: Supports unlimited open files. Each tab maintains its own highlight state and undo/redo history.
-   **Creative Sidebar (Right)**:
    -   **Phonetics**: Displays the IPA-style breakdown of the selected word.
    -   **Perfect Rhymes**: Words with identical terminal sounds.
    -   **Slant Rhymes**: Words with closely matching vowel patterns (powered by CMUDict).
    -   **Thematic Suggestions**: Synonyms and "Vibe" associates.

## 3. The Rhyme Engine

### Mosaic (Multi-word) Rhymes
Unlike simple end-rhyme detectors, LyricFlow identify "mosaic" rhymes where a single word rhymes with a combination of words (e.g., "Orange" matching "Door Hinge").

### Internal Rhyme Detection
The engine scans the entire line, not just the last word. This helps identify complex internal structures that add rhythmic complexity to your writing.

## 4. Related Concepts ("Vibe")

One of LyricFlow's most powerful features is the **Vibe Suggestion** system. Standard thesauruses give you synonyms; LyricFlow searches for **Conceptual Neighbors**:

1.  It looks up the word's "Synsets" in WordNet.
2.  It traverses **Hypernyms** (general categories) and **Hyponyms** (specific types).
3.  It filters out direct synonyms to find words that fit the "atmosphere" without sharing the exact meaning.

## 5. Performance & Debouncing

To maintain a responsive feel, we implemented a **Debounced Analysis** system. 

Heavy calculations (scanning entire verses for rhymes) only happen when you pause (set to 1500ms). This prevents the UI from stuttering while you are mid-flow, ensuring the "Dracula" theme remains smooth and elegant.

## 6. Project Session Persistence

LyricFlow creates a `.lyricproject` JSON file in your project folders. This file stores:
-   Lists of files you currently have open in tabs.
-   The last active file you were editing.
-   Cursor positions for open files.

When you re-open a folder, LyricFlow restores your exact workspace state instantly.

## 7. Recovered Unsaved Sessions

LyricFlow also keeps an app-level recovered session cache in user app data:
-   **Untitled drafts** with content.
-   **Dirty saved files** (unsaved edits).

Snapshots are written every 30 seconds and on app close. On startup, LyricFlow can restore recovered tabs automatically. If a recovered snapshot conflicts with a file changed on disk, LyricFlow prompts you to choose:
-   Use recovered snapshot.
-   Use disk version.
-   Skip that tab.

## 8. Settings Menu

A top-level `Settings -> Preferences...` dialog allows users to configure:
-   Reopen last project on startup.
-   Restore unsaved tabs.
-   Word wrap default.
-   Left/right sidebar default visibility.
-   Clearing recovered session cache for the current workspace or all workspaces.