//! Break tokens — the value-type "resume here" state for true fragmentation.

//!

//! Design: `scripts/BREAK_TOKENS_DESIGN.md` (K30a). The layout contract is

//! LayoutNG-shaped and PURE:

//!

//! ```text

//! (node, constraint_space { remaining_extent }, break_token?) -> (fragment, break_token?)

//! ```

//!

//! Tokens are OWNED, comparable value types — nothing about pagination is

//! ever written into the node tree, the layout tree, or any cache during a

//! pass (the fossil at `paged_layout.rs:1-11` documents why the mutable

//! alternative failed). Two laws every consumer may rely on:

//!

//! 1. **Determinism**: identical input (content + constraints + incoming

//!    token) produces an identical outgoing token, comparable with `==`.

//!    Equality is structural; float fields inherit text3's rounding-tolerant

//!    `Rect` comparison, which is safe in the conservative direction — a

//!    false *inequality* merely re-lays one extra page, a false *equality*

//!    cannot arise from tolerant comparison of identical-bits passes.

//! 2. **Progress**: an outgoing token never equals the incoming token of

//!    the same fragmentainer (the page loop asserts this; violating it is

//!    the NG infinite-loop class).

//!

//! `token_fingerprint` is a FAST-PATH REJECTOR for K34 convergence checks:

//! `a == b ⇒ fingerprint(a) == fingerprint(b)` (it hashes a subset of the

//! compared fields). Convergence must NEVER be decided on fingerprints

//! alone — equal fingerprints require the full `==` before stopping

//! repagination (a collision that stopped early would ship stale pages).

//!

//! Provenance note: the token SHAPE follows public architecture prose

//! (css-break-3, the `RenderingNG` fragmentation article, the `LayoutNG`

//! README); no engine implementation source was consulted. See the design

//! doc §9.

use alloc::boxed::Box;

use alloc::vec::Vec;

use crate::text3::cache::{BreakCursor, Hyphens, LineBreakStrictness, ShapedItem, WordBreak};

/// The resume state a fragmentainer boundary produced. `None` anywhere a

/// token could appear means "finished — nothing to resume".

#[derive(Debug, Clone, PartialEq)]

pub enum BreakToken {

    /// Resume a block-level box (its unfinished/unstarted children carry

    /// their own tokens).

    Block(BlockBreakToken),

    /// Resume an inline formatting context mid-flow.

    Inline(InlineBreakToken),

}

/// Resume state for one BLOCK box. Invariant (asserted by consumers, not

/// trusted): every sibling BEFORE the first entry in `children` is FINISHED

/// — `children` is the unfinished tail, in document order.

#[derive(Debug, Clone, PartialEq)]

pub struct BlockBreakToken {

    /// Layout-tree index of the box this token resumes. Tokens never

    /// outlive their layout generation (they are regenerated per pass), so

    /// the index is same-generation by construction; `generation` exists to

    /// assert that in debug builds.

    pub node: usize,

    /// Block-size of this box already consumed by previous fragmentainers.

    /// Drives `box-decoration-break: slice` (default: no re-emitted top

    /// decoration on resume) and monolith overflow resumption.

    pub consumed_block_size: f32,

    /// The unfinished tail of this box's children, document order.

    pub children: Vec<ChildBreakEntry>,

    /// Layout-generation stamp for debug assertions (see `node`).

    pub generation: u64,

}

/// One unfinished child in a [`BlockBreakToken`].

#[derive(Debug, Clone, PartialEq)]

pub enum ChildBreakEntry {

    /// The child started in an earlier fragmentainer; resume it with this

    /// token.

    ResumeIn {

        child: usize,

        token: Box<BreakToken>,

    },

    /// The child has not started yet — a break landed before it.

    /// `forced` = the break came from `break-before: page` (or a

    /// `<pagebreak/>` node): css-break-3 §5.2 truncates margins adjoining

    /// UNFORCED breaks only, so the resume side keeps this child's top

    /// margin iff the break was forced.

    BreakBefore { child: usize, forced: bool },

}

/// Owned snapshot of text3's [`BreakCursor`] — the inline resume state.

///

/// `BreakCursor` borrows `&'a [ShapedItem]` and therefore cannot be stored

/// across passes or compared as a value; this snapshot owns exactly the

/// STATE (resume index + hyphenation remainder). The style knobs on the

/// cursor (`word_break` / `hyphens` / `line_break`) are deliberately NOT

/// part of the token: they derive from style, not from layout progress —

/// [`InlineBreakToken::resume`] takes them from the caller, who reads them

/// from the same style the original cursor did.

#[derive(Debug, Clone, PartialEq)]

pub struct InlineBreakToken {

    /// Index of the next *full* item to process in the IFC's shaped-item

    /// sequence.

    pub next_item_index: usize,

    /// The remainder of an item split by hyphenation on the boundary line —

    /// the very first content of the resumed fragment.

    pub partial_remainder: Vec<ShapedItem>,

}

impl InlineBreakToken {

    /// Snapshot a live cursor's resume state (pure; the cursor is untouched).

    #[must_use]

    /// Reconstruct a cursor over `items` positioned exactly where the

    /// snapshotted one stopped. The style knobs come from the caller (they

    /// are style-derived, not layout state — see the type docs).

    #[must_use]

    /// True when resuming would start from the very beginning — such a

    /// token should not exist (it encodes "no progress"); the page loop's

    /// progress guard treats it as a hard stop.

    #[must_use]

}

// ---------------------------------------------------------------------------

// K30b decision helpers — pure, exhaustively unit-tested; `layout_bfc` only

// wires them (design §4.4)

// ---------------------------------------------------------------------------

/// Verdict for one normal-flow child against the fragmentainer.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub enum FitDecision {

    /// The child ends within the remaining extent: place it here.

    Fits,

    /// Break BEFORE this child — it (and its later siblings) resume in the

    /// next fragmentainer.

    BreakBeforeHere,

    /// The child is the first content of this fragmentainer and no

    /// fragmentainer can ever hold it: place it OVERFLOWING (css-break

    /// monolith rule — never tear, never loop).

    MonolithOverflow,

}

/// Geometry tolerance for fit checks: sub-1/100-px overshoot is float noise,

/// not a page break.

const FIT_EPS: f32 = 0.01;

/// Decide whether a child whose border-box starts at `pen` (margins already

/// resolved) and spans `child_block_size` fits the remaining extent.

///

/// `placed_any_content`: whether this fragmentainer already holds content

/// from this box — if it does, breaking before the child always makes

/// progress; if it does not, breaking only helps when a FRESH fragmentainer

/// is actually bigger than what remains here (otherwise the child is a

/// monolith and overflows).

#[must_use]

    // First content of the fragmentainer overflows on its own. Progress

    // guarantee: only defer to the next fragmentainer if it is genuinely

    // roomier than what is left here AND can hold the child.

    {

    } else {

    }

/// Build the outgoing token when a break lands before `breaking_child`:

/// the unfinished tail is that child plus every later in-flow sibling, all

/// as `BreakBefore` entries (block-granular v1 — `ResumeIn` entries appear

/// when nested resume lands, K30b part 2).

#[must_use]

    );

/// The consumer-side resume plan for a block token: which child is the

/// FIRST unfinished one (everything before it is finished and must be

/// skipped with zero side effects). `None` for a childless token —

/// defensive: such a token encodes no work and resuming from it is a

/// no-op, which the page loop's progress guard turns into a stop.

#[derive(Debug, Clone, Copy, PartialEq, Eq)]

pub struct ResumePlan {

    pub first_unfinished: usize,

}

#[must_use]

        },

// ---------------------------------------------------------------------------

// Fingerprints — fast-path rejector for K34 convergence

// ---------------------------------------------------------------------------

const FNV_OFFSET: u64 = 0xcbf2_9ce4_8422_2325;

const FNV_PRIME: u64 = 0x0000_0100_0000_01b3;

#[inline]

#[inline]

/// 64-bit structural fingerprint. Law: `a == b ⇒ fingerprint(a) ==

/// fingerprint(b)` — guaranteed because it hashes a SUBSET of the fields

/// `PartialEq` compares (float geometry inside `partial_remainder` items is

/// summarized by count + source indices, never by the tolerant-compared

/// floats themselves, so the law survives the rounding tolerance).

/// Convergence checks use it to reject fast and MUST confirm with `==`.

#[must_use]

            // consumed_block_size participates in PartialEq as an exact

            // f32 compare, so its bits are a valid fingerprint component.

                }

            }

        }

            // Source indices are integer-exact fields of the compared items

            // (Rect floats are deliberately excluded — they compare with a

            // rounding tolerance, hashing them would break the law).

            }

        }

    }

// Returns Option to mirror the other `*_source` accessors and to stay

// source-compatible if a future `ShapedItem` variant has no content index.

#[allow(clippy::unnecessary_wraps)]

    }

// ---------------------------------------------------------------------------

// Property tests (K30a exit gate; see design doc §6.2)

// ---------------------------------------------------------------------------

#[cfg(test)]

mod break_token_laws {

    use azul_core::selection::ContentIndex;

    use super::*;

    use crate::text3::cache::Rect;

    // -- Eq laws ----------------------------------------------------------

    #[test]

            7,

            120.5,

            ],

        );

        // Any structural difference breaks equality: node…

        // …consumed size…

        // …child order (document order is semantic)…

        // …and nested inline state.

    #[test]

            );

        }

        // And it actually discriminates the obvious cases (not a constant).

        );

        );

    #[test]

        // text3's Rect PartialEq is rounding-tolerant: two tokens whose

        // remainder Rects differ inside the tolerance are EQUAL — the

        // fingerprint must agree (law: a == b ⇒ fp(a) == fp(b)). This is

        // exactly why Rect floats are excluded from the fingerprint.

        } else {

            // If the tolerance ever tightens to bit-exact this branch keeps

            // the test meaningful instead of vacuous.

        }

    // -- Cursor bridge ----------------------------------------------------

    #[test]

        );

        // And the snapshot round-trips through the snapshot again.

    #[test]

    // -- K30b decision helpers ---------------------------------------------

    #[test]

        use FitDecision::*;

        // Fits exactly / with epsilon slack.

        // Mid-page overflow with content already placed: break before.

        // First content, uniform pages, taller than a page: monolith.

            MonolithOverflow

        );

        // First content, but the NEXT page is roomier and holds it: defer.

            BreakBeforeHere

        );

        // First content, next page roomier but STILL too small: monolith

        // (deferring would just move the overflow, not fix it).

            MonolithOverflow

        );

        // Progress guarantee: never break-before on first content when the

        // next fragmentainer is the same size (would loop forever).

            MonolithOverflow

        );

    #[test]

        };

            b.children,

            ]

        );

        // Consumer side: resume starts exactly at the breaking child.

    #[test]

    // -- Progress guard shape ----------------------------------------------

    #[test]

        // The page loop's no-progress guard is `outgoing == incoming`; pin

        // that "one more child finished" and "one more item consumed" are

        // both visible to it.

            0,

            0.0,

            ],

        );

            0,

            0.0,

        );

            0,

            0.0,

            ],

        );

}