Automated changelog | Aug 01 - Aug 08 | 28 hours (4 active days)

Automated changelog | Aug 01 - Aug 08 | 28 hours (4 active days)

Architecture & Performance

This period saw a major architectural refactor focused on boosting real-time editor performance and laying the groundwork for advanced features.

• Optimized Element Detection Service: The ElementDetectionService has been re-architected with a “Dual Method” approach to drastically reduce processing overhead during live typing.
  • Implementation: The original detectElementType method has been renamed to detectElementTypeImport, intended for initial file parsing where context is pre-built. A new, highly optimized detectElementTypeRealTime method was introduced for live editor interactions.
  • Technical Details: The detectElementTypeRealTime method implements a “fast-path” that handles over 80% of typing scenarios (like dialogue continuation) with zero memory allocation. It achieves this by prioritizing checks on forced syntax and previous element types (previousElementTypes) before falling back to a lazy context builder (buildContext closure). This avoids expensive document traversal on every keystroke.
  • Impact: This change delivers a significant performance improvement (estimated 85-95%) and reduces memory churn, resulting in a much more responsive editor experience. The new architecture is detailed in SCRIPT_ELEMENT_DETECTION_OPTIMIZATION_PLAN.md.
• Standardized Context Building: The FountainContextUtils service was updated to provide a consistent and limited context window for element detection.
  • Implementation: The buildContextForNode and buildContextForLine methods now enforce a strict limit of 20 previous lines for context.
  • Impact: This ensures predictable and performant behavior for the element detection service, preventing slowdowns in very large documents.
• Optimized Syntax Detection: The core FountainSyntaxDetector received significant performance enhancements.
  • Implementation: The isBasicCharacterName method was heavily optimized using a “fail-fast” strategy, replacing many regular expressions with direct character code checks. The isDialogueWithContext method now leverages a history of previousElementTypes for more accurate and performant detection. Regex patterns have been pre-compiled as static constants to reduce overhead.
  • Impact: These optimizations contribute to faster parsing and more accurate real-time element identification across the application.
• Real-time Controller Integration: The FountainRealtimeController was updated to leverage these new performance optimizations.
  • Implementation: The controller now calls the new detectElementTypeRealTime service method, providing the lazy buildContext closure. A new _collectPreviousElementTypes helper was added to gather metadata from previous nodes, feeding crucial information into the new fast-path detection logic.

New Feature: Real-time Script Analytics

A comprehensive, real-time script analytics service has been implemented, providing live statistical feedback to the user without impacting editor performance.

• Analytics Service & Data Models:
  • Implementation: A new ScriptAnalyticsService was introduced. It hooks into the FountainRealtimeController to receive document change notifications and updates analytics via a debounced Stream. The core innovation is its high-performance design: instead of re-parsing text, it iterates through SuperEditor’s ParagraphNodes and reads the pre-calculated fountainType from node.metadata.
  • Data Models: New data models were created to support this feature: ScriptAnalytics (for overall script stats like element counts and page estimation) and CharacterStats (for per-character metrics like dialogue lines and estimated screen time). These models include copyWith and JSON serialization methods.
• Industry-Standard Page Calculation:
  • Implementation: A new ScreenplayPageCalculator service was added. It uses industry-standard rules (e.g., 55 lines per page) and element-specific line weights (elementLineWeights) to provide an accurate page count, complete with fractional formatting (e.g., “22 3/4 pages”).
• UI Components:
  • Implementation: New widgets ScriptAnalyticsPanel and ScriptAnalyticsSidebar were created to display the live data from the service. The panel offers a responsive layout, showing a compact view (isCompact: true) on smaller screens and a full breakdown on larger ones.

Script Parsers & Text Processing

Significant improvements were made to the text processing pipeline to increase robustness and fix formatting issues.

• FDX Parser - Empty Line Restoration: A critical formatting regression in the FDX parser has been fixed.
  • Implementation: A post-processing step, _insertStandardEmptyLines, has been added to the fdx_parser. This method uses rule-based helpers (_needsEmptyLineBefore, _needsEmptyLineAfter) to intelligently insert empty ScenePart objects between screenplay elements, conforming to industry formatting standards. The logic includes critical checks to prevent the insertion of double empty lines.
  • Impact: Imported FDX files now render with the correct, readable spacing between elements.
• Unicode Normalization: A robust Unicode character normalization step was added to the text processing pipeline.
  • Implementation: The FountainTextProcessor now includes a normalizeUnicodeCharacters method. This method converts common typographic characters (e.g., smart quotes ‘ ’ “ ”, em/en dashes — –) into their standard ASCII equivalents before parsing. It includes a fast-path check (_isUnicodeCharacterThatNeedsNormalization) to bypass the process if no special characters are found.
  • Impact: This makes all text-based parsers (Fountain, PDF) significantly more robust, ensuring consistent parsing of text copied from various sources.
• Enhanced Text Cleanup: The TextCleanupUtils for pre-processing raw text has been improved.
  • Implementation: The page indicator detection regex (_isPageIndicator, _isConsecutivePageIndicator) was updated to correctly identify and remove page numbers that have trailing periods (e.g., “6.”).
• Performance Instrumentation: The FountainTextProcessor and PdfParser have been instrumented with Stopwatch-based logging to measure and analyze performance during parsing, including metrics like lines/sec.

UI & Theming

• Simple Color Theming Toggle: A minimal, state-managed color theming feature has been added to the editor.
  • Implementation: A new ColorThemingNotifier (a Riverpod StateNotifier<bool>) was introduced in simple_editor_theming.dart to manage a simple on/off state. The FountainFormattedEditorWidget is now a ConsumerWidget that watches this state via the editorColorThemingProvider.
  • Stylesheet & Keyboard Action: The FountainStylesheets class was updated to apply background colors to elements when theming is enabled. A new keyboard action, createFountainColorThemingAction (Cmd/Ctrl+Shift+T), was added to toggle the state.
  • Impact: Users can now toggle a color-coded view of the script for better element distinction.

Stability & Error Handling

• Keyboard Error Boundary: A critical stability improvement was added to the script editor.
  • Implementation: The ScriptEditorWidget now wraps the SuperEditor instance in a custom FlutterErrorBoundary. This boundary specifically catches the KeyDownEvent assertion error that was causing editor freezes. When the error is caught, it triggers a recovery routine (_recoverFromKeyboardError) that resets the editor’s focus state, preventing a crash.
  • Impact: This makes the editor significantly more resilient to a known Flutter framework assertion, improving overall stability.