Module shaping_fallback 

Deterministic fallback path for shaped text rendering.

When the shaping engine is unavailable (no font data, feature disabled, or runtime budget exceeded), this module provides a guaranteed fallback that preserves:

1. Semantic correctness: all grapheme clusters are rendered.
2. Interaction stability: cursor, selection, and copy produce identical results regardless of whether shaping was used.
3. Determinism: the same input always produces the same output.

Fallback strategy

The ShapingFallback struct wraps an optional shaper and transparently degrades when shaping is unavailable or fails:

  RustybuzzShaper available → use shaped rendering
      ↓ (failure or unavailable)
  NoopShaper → terminal/monospace rendering (always succeeds)

Ligature-sensitive flows are explicitly policy-controlled via LigatureMode:

• Auto: preserve caller-provided feature set; if ligatures are unsupported, force-disable standard ligatures for deterministic canonical output.
• Enabled: force standard ligatures on when supported.
• Disabled: force canonical grapheme boundaries.

If ligatures are requested but unsupported by RuntimeCapability, fallback returns deterministic canonical grapheme rendering.

Both paths produce a ShapedLineLayout with identical interface, ensuring downstream code (cursor navigation, selection, copy) works without branching on which path was taken.

Example

use ftui_text::shaping_fallback::{ShapingFallback, FallbackEvent};
use ftui_text::shaping::NoopShaper;
use ftui_text::script_segmentation::{Script, RunDirection};

// Create a fallback that always uses NoopShaper (terminal mode).
let fallback = ShapingFallback::terminal();
let (layout, event) = fallback.shape_line("Hello!", Script::Latin, RunDirection::Ltr);

assert_eq!(layout.total_cells(), 6);
assert_eq!(event, FallbackEvent::NoopUsed);

Structs

FallbackStats

Accumulated fallback statistics for monitoring quality degradation.

ShapingFallback

Transparent shaping with guaranteed fallback.

Enums

FallbackEvent

Diagnostic event describing which path was taken.

LigatureMode

Explicit ligature-mode policy for shaping fallback.