Meridian Write — спецификация приложения

// kernel/crates/text-model/src/document.rs

/// Стабильный идентификатор узла: старшие 32 бита — клиент (0 = локальный), младшие — счётчик.
/// Stable node id: high 32 bits — client id (0 = local), low 32 bits — counter. Совместим с Yrs (client, clock).
#[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct NodeId(pub u64);
pub type ParaId = NodeId;
pub type TableId = NodeId;
pub type ObjectId = NodeId;

pub struct Document {
    pub id: DocId,                       // UUID документа / document UUID (meta.xml)
    pub meta: Metadata,                  // Dublin Core + свои / Dublin Core + custom
    pub settings: DocSettings,           // совместимость, вид, защита, слияние / compat, view, protection, mail merge
    pub theme: Theme,                    // цвета/шрифты темы / theme colors & fonts
    pub fonts: FontTable,                // объявленные шрифты, встроенные подмножества / declared & embedded fonts
    pub styles: StyleSheet,
    pub numbering: NumberingDefs,
    pub body: Body,
    pub footnotes: NoteStore,            // тела сносок по id / footnote bodies by id
    pub endnotes: NoteStore,
    pub comments: CommentStore,
    pub bookmarks: BookmarkStore,
    pub revisions: RevisionStore,        // авторы, даты, перемещения / authors, dates, moves
    pub fields: FieldIndex,              // индекс полей для обновления / field index for updates
    pub media: MediaStore,               // blob-ы media/, objects/ / blobs
    pub glossary: Vec<GlossaryEntry>,    // автотекст / autotext (в шаблонах)
    pub scripts: ScriptManifest,
    pub sources: BibliographySources,    // источники цитирования / citation sources
    pub custom_xml: Vec<CustomXmlPart>,  // round-trip
    pub extensions: ExtensionBag,        // неизвестные элементы чужих форматов / unknown foreign elements
    pub interner: PropsInterner,         // хэш-консинг свойств / props hash-consing
    pub oplog: OpLog,                    // журнал операций (история, автосохранение) / operation journal
}

pub struct Body { pub sections: Vec<Section> }

pub struct Section {
    pub id: NodeId,
    pub props: SectionProps,             // см. 4.6
    pub blocks: BlockList,               // последовательность блоков / block sequence
    pub headers: HeaderFooterSet,        // default / first / even (каждый — BlockList)
    pub footers: HeaderFooterSet,
}

/// Список блоков с суммарными длинами для O(log n) поиска по позиции (B-дерево порядка 32).
/// Block list with prefix sums for O(log n) position lookup (B-tree, order 32).
pub struct BlockList { tree: SumTree<Block, BlockSummary> }
pub struct BlockSummary { pub chars: u64, pub paras: u32, pub blocks: u32 }

pub enum Block {
    Paragraph(Paragraph),
    Table(Table),
    Sdt(ContentControlBlock),            // элемент управления блочного уровня / block-level content control
}

pub struct Paragraph {
    pub id: ParaId,
    pub style: StyleId,                  // стиль абзаца (всегда есть; по умолчанию "Normal")
    pub props: ParaPropsId,              // прямое форматирование абзаца / direct paragraph formatting
    pub mark_props: CharPropsId,         // свойства знака абзаца ¶ / paragraph mark run properties
    pub text: ParaText,                  // см. 4.3
    pub runs: SpanList<CharPropsId>,     // прямое форматирование символов / direct run formatting
    pub rev: SpanList<RevSpan>,          // слой исправлений / revision layer (4.9)
    pub markers: MarkerMap,              // поля, объекты, сноски, разрывы (занимают 1 символ U+FFFC)
    pub anchors: AnchorList,             // закладки/комментарии (нулевой ширины) / zero-width anchors
    pub section_break: Option<Box<SectionProps>>, // только у последнего абзаца раздела при импорте docx
    pub cache: ParaCache,                // хэш текста, язык, номер списка, раскладка (не сериализуется)
}

/// Элементы, занимающие один символ-заполнитель U+FFFC в тексте абзаца.
/// Inline elements occupying one placeholder char U+FFFC in paragraph text.
pub enum Marker {
    FieldStart { field: FieldId },       // { начало поля / field begin
    FieldSeparate { field: FieldId },    // | разделитель код/результат
    FieldEnd { field: FieldId },         // } конец поля
    FootnoteRef { note: NoteId, custom_mark: Option<String> },
    EndnoteRef { note: NoteId, custom_mark: Option<String> },
    InlineObject { object: ObjectId },   // рисунок/фигура/формула/диаграмма в тексте / inline drawing
    AnchoredObject { object: ObjectId }, // плавающий объект, якорь здесь / floating object anchored here
    Break(BreakKind),                    // Line | Page | Column | TextWrapping{clear}
    Symbol { font: FontRef, code: u32 }, // w:sym
    Ruby { base: Box<ParaText>, text: Box<ParaText>, props: RubyProps },
    CommentRef { comment: CommentId },   // знак комментария / comment reference mark
    SdtStart { sdt: SdtId }, SdtEnd { sdt: SdtId }, // инлайновый элемент управления
    Separator(SeparatorKind),            // разделитель сносок / footnote separator (только в телах сносок)
    PageNumber,                          // устаревший w:pgNum
    Tab,                                 // '\t' хранится как символ; маркер только для w:ptab (абс. таб.)
}
// Обычная табуляция — символ '\t', разрыв строки — '\u{000B}', неразрывный пробел — U+00A0, мягкий перенос —
// U+00AD, неразрывный дефис — U+2011. Так поиск и правописание работают по «плоскому» тексту.

/// Позиция в документе (стабильная): абзац + смещение в скалярных значениях Unicode.
/// Stable document position: paragraph + offset in Unicode scalar values.
#[derive(Copy, Clone, PartialEq, Eq)]
pub struct Position { pub para: ParaId, pub offset: u32 }

/// Путь для навигации по дереву (вычисляется из ParaId через индекс документа за O(log n)).
/// Tree path (resolved from ParaId via document index in O(log n)).
pub struct BlockPath { pub section: u16, pub steps: SmallVec<[PathStep; 4]> }
pub enum PathStep { Block(u32), Cell { row: u16, col: u16 }, Note(NoteId), Header(HfKind), TextBox(ObjectId) }

pub struct Table {
    pub id: TableId,
    pub style: StyleId,
    pub props: TablePropsId,             // ширина, выравнивание, отступ, границы, поля ячеек, плавающая позиция
    pub grid: Vec<Twips>,                // сетка колонок / column grid (как w:tblGrid)
    pub rows: Vec<TableRow>,
    pub look: TableLook,                 // флаги условного форматирования стиля / firstRow, lastRow, …
    pub caption: Option<String>, pub description: Option<String>, // доступность / accessibility
}
pub struct TableRow {
    pub id: NodeId,
    pub props: RowPropsId,               // высота + правило, ☐ заголовок, ☐ разрешить разрыв, выравнивание
    pub cells: Vec<TableCell>,
    pub rev: Option<RevId>,              // вставка/удаление строки как исправление / row ins/del revision
}
pub struct TableCell {
    pub id: NodeId,
    pub props: CellPropsId,              // ширина, grid_span, v_merge: Restart|Continue, границы, заливка,
                                         // поля, верт. выравнивание, направление, ☐ no_wrap, ☐ fit_text
    pub blocks: BlockList,               // вложенное содержимое, включая таблицы / nested content incl. tables
    pub rev: Option<RevId>,
}

pub enum ParaText { Small(SmallString<64>), Rope(Rope) }   // переключение при > 4096 байт

pub struct SpanList<T: Copy + Eq> { spans: SpanStorage<T> }   // инвариант: Σ len == text.len_chars()
pub struct Span<T> { pub len: u32, pub value: T }

impl<T: Copy + Eq> SpanList<T> {
    pub fn value_at(&self, offset: u32) -> T;                       // O(log n)
    pub fn insert(&mut self, offset: u32, len: u32, value: T);      // расщепляет спан, сливает равных соседей
    pub fn remove(&mut self, range: Range<u32>);
    pub fn set(&mut self, range: Range<u32>, f: impl Fn(T) -> T);   // патч на диапазоне / patch over range
    pub fn iter(&self, range: Range<u32>) -> impl Iterator<Item = (Range<u32>, T)>;
}

// Все поля Option: None = «не задано, наследовать». All fields are Option: None = inherit.
#[derive(Clone, PartialEq, Eq, Hash, Default)]
pub struct CharProps {
    pub font: Option<FontSet>,           // ascii, h_ansi, east_asia, cs (+ hint)
    pub size: Option<HalfPoints>, pub size_cs: Option<HalfPoints>,
    pub bold: Option<bool>, pub bold_cs: Option<bool>,   // toggle-свойства / toggle properties
    pub italic: Option<bool>, pub italic_cs: Option<bool>,
    pub caps: Option<bool>, pub small_caps: Option<bool>, pub strike: Option<bool>, pub dstrike: Option<bool>,
    pub outline: Option<bool>, pub shadow: Option<bool>, pub emboss: Option<bool>, pub imprint: Option<bool>,
    pub vanish: Option<bool>, pub web_hidden: Option<bool>,
    pub underline: Option<Underline>,    // стиль + цвет / style + color
    pub color: Option<Color>, pub highlight: Option<Highlight>, pub shading: Option<Shading>,
    pub spacing: Option<Twips>,          // разрядка / tracking
    pub position: Option<HalfPoints>,    // смещение / raise-lower
    pub scale: Option<u16>,              // масштаб % / horizontal scale
    pub kern: Option<HalfPoints>,
    pub vert_align: Option<VertAlign>,   // Baseline | Superscript | Subscript
    pub lang: Option<LangSet>,           // val, east_asia, bidi
    pub rtl: Option<bool>, pub cs: Option<bool>,
    pub no_proof: Option<bool>, pub snap_to_grid: Option<bool>,
    pub em: Option<EmphasisMark>, pub east_asian_layout: Option<EastAsianLayout>, pub fit_text: Option<FitText>,
    pub ot_features: Option<OtFeatures>, // лигатуры, цифры, ss01..20, cntxt + произвольные теги / OpenType
    pub effects: Option<Arc<TextEffects>>, // w14: контур/тень/свечение/градиент (большой, редкий → Arc)
    pub style: Option<StyleId>,          // ссылка на стиль символов / character style ref (rStyle)
    pub ext: Option<Arc<ExtensionBag>>,
}

#[derive(Clone, PartialEq, Eq, Hash, Default)]
pub struct ParaProps {
    pub alignment: Option<Alignment>,    // Left|Center|Right|Both|Distribute|ThaiDistribute|…
    pub indent: Option<Indent>,          // left, right, first_line, hanging, (chars-варианты для CJK), mirror
    pub spacing: Option<ParaSpacing>,    // before, after, before_auto, after_auto, line, line_rule, contextual
    pub keep_next: Option<bool>, pub keep_lines: Option<bool>, pub widow_control: Option<bool>,
    pub page_break_before: Option<bool>, pub suppress_line_numbers: Option<bool>,
    pub suppress_auto_hyphens: Option<bool>,
    pub outline_level: Option<u8>,       // 0..=8, 9 = основной текст / body text
    pub borders: Option<Arc<ParaBorders>>, pub shading: Option<Shading>,
    pub tabs: Option<Arc<TabStops>>,     // включая «очищенные» позиции / incl. cleared stops
    pub numbering: Option<NumRef>,       // num_id + ilvl; num_id == 0 — «нет списка» явно
    pub bidi: Option<bool>, pub text_direction: Option<TextDirection>,
    pub frame: Option<Arc<FrameProps>>,  // рамки .doc / legacy frames
    pub cjk: Option<CjkParaProps>,       // kinsoku, overflow_punct, top_line_punct, auto_space_*, snap_to_grid
    pub mirror_indents: Option<bool>, pub text_alignment: Option<TextAlignment>, // baseline/center/…
    pub div_id: Option<u32>,             // HTML-импорт / html div
    pub ext: Option<Arc<ExtensionBag>>,
}

pub struct Style {
    pub id: StyleId,                     // интернированный styleId (как в docx: "Heading1")
    pub name: String,                    // отображаемое имя, локализуется по таблице Word RU/EN
    pub kind: StyleKind,                 // Paragraph | Character | Linked | Table | Numbering
    pub based_on: Option<StyleId>, pub next: Option<StyleId>, pub link: Option<StyleId>,
    pub para: ParaPropsId, pub chars: CharPropsId,
    pub table: Option<Arc<TableStyle>>,  // базовые свойства + условные форматы / conditional formats
    pub numbering: Option<NumberingId>,  // для StyleKind::Numbering
    pub ui_priority: u16, pub hidden: bool, pub semi_hidden: bool, pub unhide_when_used: bool,
    pub quick_style: bool, pub locked: bool, pub auto_redefine: bool, pub custom: bool,
}

pub struct StyleSheet {
    pub styles: IndexMap<StyleId, Style>,
    pub doc_defaults: (ParaPropsId, CharPropsId),   // w:docDefaults
    pub latent: LatentStyles,
    cache: ResolveCache,                 // (para_style, char_style, direct ids…) → ResolvedProps
}

pub struct ResolveCtx<'a> { sheet: &'a StyleSheet, numbering: &'a NumberingDefs, table: Option<TableCtx> }

impl StyleSheet {
    /// Разрешить свойства символов для run. / Resolve effective character properties for a run.
    pub fn resolve_char(&self, cx: &ResolveCtx, para: &Paragraph, run_props: CharPropsId) -> &ResolvedChar {
        let key = (cx.table_key(), para.style, para.props, run_props);
        self.cache.get_or_insert(key, || {
            let mut acc = ResolvedChar::from(self.doc_defaults.1);
            if let Some(t) = cx.table_style_chain() { for s in t { acc.apply_char(s.chars) } }
            if let Some(num) = para_num_level(cx, para) { acc.apply_char(num.chars) }
            let pchain = self.chain(para.style);        // корень → лист / root → leaf
            let mut toggles = ToggleAcc::default();      // XOR-аккумулятор toggle-свойств
            for s in &pchain { acc.apply_char_with_toggles(s.chars, &mut toggles) }
            let rp = cx.interner.chars(run_props);
            if let Some(cs) = rp.style { for s in self.chain(cs) { acc.apply_char_with_toggles(s.chars, &mut toggles) } }
            acc.apply_direct_char(rp, &toggles);         // прямое: toggle задаёт абсолютное значение
            acc.finish(cx)                               // шрифт по письменности, размер cs, язык по умолчанию
        })
    }
}

pub struct NumberingDefs {
    pub abstract_nums: IndexMap<AbstractNumId, AbstractNum>,
    pub instances: IndexMap<NumId, NumInstance>,
}
pub struct AbstractNum {
    pub id: AbstractNumId,
    pub multi_level: MultiLevelType,     // Single | Multilevel | HybridMultilevel
    pub levels: [Level; 9],
    pub style_link: Option<StyleId>,     // этот abstractNum определяет стиль списка / defines list style
    pub num_style_link: Option<StyleId>, // ссылается на стиль списка / references list style
    pub name: Option<String>,            // имя списка в UI / list name shown in UI
}
pub struct Level {
    pub start: i32,
    pub fmt: NumFmt,                     // Decimal | UpperRoman | LowerRoman | UpperLetter | LowerLetter | Ordinal |
                                         // CardinalText | OrdinalText | Bullet | DecimalZero | RussianLower | RussianUpper |
                                         // Chicago | IdeographDigital | JapaneseCounting | … | Custom(String) | None
    pub text: LevelText,                 // шаблон "%1.%2." → [Lit("…"), LevelRef(0), Lit("."), …]
    pub justify: Alignment,              // выравнивание номера / number alignment
    pub para: ParaPropsId,               // отступы/табуляции уровня / level indents & tabs
    pub chars: CharPropsId,              // шрифт номера/маркера / number run props
    pub suffix: LevelSuffix,             // Tab | Space | Nothing
    pub restart_after: Option<u8>,       // перезапуск после уровня (lvlRestart; 0 = никогда) / restart after level
    pub legal: bool,                     // isLgl
    pub pic_bullet: Option<MediaId>,
    pub tentative: bool,
}
pub struct NumInstance {
    pub id: NumId,
    pub abstract_id: AbstractNumId,
    pub overrides: [Option<LevelOverride>; 9],   // startOverride и/или полная замена уровня / level override
}
pub struct LevelOverride { pub start: Option<i32>, pub level: Option<Box<Level>> }
pub struct NumRef { pub num_id: NumId, pub ilvl: u8 }

pub struct SectionProps {
    pub break_kind: SectionBreak,        // NextPage | Continuous | EvenPage | OddPage | NextColumn
    pub page: PageSize,                  // width, height (twips), orientation, paper code
    pub margins: PageMargins,            // top, bottom, left, right, header, footer, gutter, gutter_at_top
    pub columns: Columns,                // count, space, equal_width, cols: Vec<(width, space)>, separator
    pub title_page: bool,                // особый колонтитул первой / different first page
    pub page_numbering: PageNumbering,   // fmt, start: Option<i32>, chapter_style: Option<u8>, chapter_sep
    pub line_numbering: Option<LineNumbering>, // count_by, start, distance, restart: NewPage|NewSection|Continuous
    pub vertical_align: VAlign,          // Top | Center | Both | Bottom
    pub text_direction: TextDirection,   // LrTb | TbRl | BtLr | LrTbV | TbRlV | TbLrV
    pub bidi: bool, pub rtl_gutter: bool,
    pub footnote_props: NoteProps,       // pos, num_fmt, num_start, num_restart, columns
    pub endnote_props: NoteProps,
    pub doc_grid: DocGrid,               // Default | Lines | LinesAndChars | SnapToChars; line_pitch, char_space
    pub borders: Option<Arc<PageBorders>>,
    pub paper_source: Option<PaperSource>,
    pub protection: Option<SectionProtection>, // form protection
    pub ext: Option<Arc<ExtensionBag>>,
}
pub struct HeaderFooterSet { pub default: Option<BlockList>, pub first: Option<BlockList>, pub even: Option<BlockList> }
// Отсутствующий колонтитул = «как в предыдущем разделе» (linkToPrevious) / missing = link to previous.

pub struct DrawingObject {
    pub id: ObjectId,
    pub kind: DrawingKind,               // Picture(PictureProps) | Shape(SceneNodeId) | Group(Vec<ObjectId>) |
                                         // TextBox(TextBoxProps + BlockList) | Chart(ChartId) | Math(MathId) |
                                         // Canvas(Vec<ObjectId>) | Ole(OleRef) | Sheet(EmbeddedSheet)
    pub size: Size,                      // EMU / extent
    pub transform: Transform2D,          // поворот, отражение / rotation, flip
    pub placement: Placement,            // Inline(InlineProps) | Anchored(AnchorProps)
    pub alt: AltText,                    // title, description, decorative
    pub name: String, pub hidden: bool, pub locked: bool,
    pub hyperlink: Option<Hyperlink>,
    pub style: ShapeStyle,               // заливка, контур, эффекты (общие с Draw) / fill, line, effects
    pub ext: Option<Arc<ExtensionBag>>,
}
pub struct AnchorProps {
    pub h: HPos,                         // rel: Margin|Page|Column|Character|LeftMargin|RightMargin|InsideMargin|OutsideMargin
                                         // + Align(Left|Center|Right|Inside|Outside) | Offset(Emu) | PctOffset(f32)
    pub v: VPos,                         // rel: Margin|Page|Paragraph|Line|TopMargin|BottomMargin|Inside|Outside
                                         // + Align(Top|Center|Bottom|Inside|Outside) | Offset(Emu) | PctOffset
    pub wrap: Wrap,                      // None{behind: bool} | Square{sides} | Tight{polygon, sides} |
                                         // Through{polygon, sides} | TopAndBottom
    pub dist: Insets,                    // расстояние до текста / distance from text (EMU)
    pub z: i32, pub behind_text: bool, pub allow_overlap: bool, pub layout_in_cell: bool,
    pub locked: bool,                    // зафиксировать якорь / lock anchor
    pub move_with_text: bool,            // v.rel == Paragraph|Line ⇒ true
    pub rel_size: Option<RelSize>,       // ширина/высота в % от поля/страницы / relative size
    pub simple_pos: Option<Point>,       // старые документы / legacy
}

pub struct Field {
    pub id: FieldId,
    pub code: FieldCode,                 // разобранный код / parsed instruction
    pub instr_text: String,              // исходная строка кода (для round-trip и неизвестных полей)
    pub switches: Switches,              // \* \# \@ \! \h и специфичные / general & field-specific switches
    pub para: ParaId,                    // абзац маркера FieldStart (поля не пересекают абзацы, кроме
                                         // устаревших — тогда хранится цепочка маркеров по абзацам)
    pub dirty: bool, pub locked: bool,   // требует обновления / заблокировано
    pub nested_in: Option<FieldId>,
    pub kind: FieldKind,                 // Simple (w:fldSimple) | Complex (маркеры) — влияет только на запись docx
    pub cached_result: Option<String>,   // для полей без Separate (fldSimple) и для сравнения
}
pub enum FieldCode {
    Page, NumPages, SectionPages, Section, Date(DateFmt), Time(DateFmt), CreateDate, SaveDate, PrintDate, EditTime,
    Seq { ident: String, bookmark: Option<String>, reset_level: Option<u8>, reset_to: Option<i32>, hide: bool, next: bool },
    Ref { bookmark: String, hyperlink: bool, number: RefNumber, above_below: bool, suppress_nondelim: bool },
    PageRef { bookmark: String, hyperlink: bool, above_below: bool },
    NoteRef { bookmark: String, hyperlink: bool, footnote_fmt: bool, above_below: bool },
    StyleRef { style: String, number: RefNumber, from_bottom: bool, raw_number: bool },
    Toc(TocOptions), Index(IndexOptions), Tc { text: String, level: u8, omit_page: bool, ident: Option<String> },
    Xe { entry: String, sub: Vec<String>, see: Option<String>, range_bookmark: Option<String>, bold: bool, italic: bool },
    Hyperlink { target: String, location: Option<String>, tooltip: Option<String>, frame: Option<String>, new_window: bool },
    MergeField { name: String, before: Option<String>, after: Option<String>, mapped: bool, vertical: bool },
    MergeRec, MergeSeq, Next, NextIf(Compare), SkipIf(Compare), If { cond: Compare, then: Expr, else_: Expr },
    Set { bookmark: String, value: Expr }, Ask { bookmark: String, prompt: String, default: Option<String>, once: bool },
    FillIn { prompt: String, default: Option<String>, once: bool }, Compare(Compare),
    Formula(FormulaAst),                 // = SUM(ABOVE) * 2
    DocProperty(String), Author, Title, Subject, Keywords, Comments, Template, FileName { with_path: bool },
    FileSize { kb: bool, mb: bool }, NumChars, NumWords, UserName, UserInitials, UserAddress, LastSavedBy, RevNum,
    Citation { tag: String, locator: Option<String>, prefix: Option<String>, suffix: Option<String>, suppress: SuppressFlags },
    Bibliography { style: Option<String>, filter_lang: Option<u32> },
    Symbol { code: u32, font: Option<String>, size: Option<HalfPoints> }, Quote(Expr), IncludeText(IncludeOpts),
    IncludePicture { path: String, data: bool }, Link(LinkOpts), Embed(EmbedOpts), MacroButton { script: String, label: String },
    ListNum { name: Option<String>, level: Option<u8>, start: Option<i32> }, AutoNum(AutoNumKind), AddressBlock(AddrOpts),
    GreetingLine(GreetOpts), Database(DbOpts), Print(String), GotoButton { target: String, label: String },
    FormText(FormTextOpts), FormCheckBox(FormCheckOpts), FormDropDown(FormDropOpts), Advance(AdvanceOpts), Eq(String),
    Barcode(BarcodeOpts), Rd { path: String, relative: bool }, Ta(TaOpts), Toa(ToaOpts),
    Unknown { name: String },
}
pub struct FieldIndex {
    pub by_id: HashMap<FieldId, Field>,
    pub by_kind: HashMap<Discriminant<FieldCode>, Vec<FieldId>>,
    pub deps: DepGraph<FieldId, Dep>,    // ребра: поле → источник (закладка, стиль, SEQ-счётчик, страница) / 5.20
}

#[derive(Copy, Clone, PartialEq, Eq, Hash, Default)]
pub struct RevSpan {
    pub ins: Option<RevId>,              // вставлено в исправлении / inserted by revision
    pub del: Option<RevId>,              // удалено в исправлении / deleted by revision
    pub moved_from: Option<RevId>, pub moved_to: Option<RevId>, // перемещение (пара с общим move_id)
    pub fmt: Option<RevId>,              // изменение формата (старые свойства — в RevisionStore) / format change
}
pub struct Revision {
    pub id: RevId, pub author: AuthorId, pub date: Timestamp,
    pub kind: RevKind,
}
pub enum RevKind {
    Insert, Delete, MoveFrom { move_id: MoveId }, MoveTo { move_id: MoveId },
    CharFormat { old: CharPropsId }, ParaFormat { old: ParaPropsId, old_style: StyleId },
    ParaMarkInsert, ParaMarkDelete,      // вставка/удаление ¶ (слияние абзацев) / paragraph mark ins/del
    SectionProps { old: Box<SectionProps> }, TableProps { old: TablePropsId }, RowProps, CellProps,
    RowInsert, RowDelete, CellInsert, CellDelete, CellMerge { old_grid: Vec<Twips> },
    NumberingChange { old: Option<NumRef> }, ObjectInsert, ObjectDelete, ObjectProps { old: Arc<AnchorProps> },
}
pub struct RevisionStore { pub revisions: HashMap<RevId, Revision>, pub authors: IndexMap<AuthorId, Author>, pub moves: HashMap<MoveId, (RevId, RevId)> }

pub struct Anchor { pub pos: Position, pub gravity: Gravity } // Gravity::Left | Right: куда «тянется» при вставке в точку
pub struct Bookmark {
    pub id: BookmarkId, pub name: String,
    pub start: Anchor, pub end: Anchor,  // start == end — точечная закладка / point bookmark
    pub hidden: bool,                    // _Toc12345 и подобные / auto-generated
    pub table_cols: Option<(u16, u16)>,  // закладка на столбцы таблицы / column bookmark (w:colFirst/colLast)
}
pub struct Comment {
    pub id: CommentId, pub author: AuthorId, pub initials: String, pub date: Timestamp,
    pub range: (Anchor, Anchor),         // диапазон; для «точечного» — ref-маркер / range or point
    pub body: BlockList,                 // форматированный текст, рисунки / rich body
    pub parent: Option<CommentId>,       // ответ в ветке / reply
    pub resolved: bool,                  // w15:done
    pub durable_id: u32,                 // w16cid для round-trip
}

pub enum Op {
    // текст / text
    InsertText { para: ParaId, at: u32, text: Arc<str>, props: CharPropsId, rev: RevSpan },
    DeleteText { para: ParaId, range: Range<u32>, removed: Arc<Fragment> }, // Fragment: text + все слои + маркеры + анкеры
    SetCharSpans { para: ParaId, range: Range<u32>, patch: CharPatch, prev: Arc<[(Range<u32>, CharPropsId)]> },
    SetRevSpans { para: ParaId, range: Range<u32>, new: RevSpan, prev: Arc<[(Range<u32>, RevSpan)]> },
    // абзац / paragraph
    SetParaProps { para: ParaId, new: ParaPropsId, prev: ParaPropsId },
    SetParaStyle { para: ParaId, new: StyleId, prev: StyleId },
    SplitParagraph { para: ParaId, at: u32, new_para: ParaId, inherit: SplitInherit },
    MergeParagraphs { first: ParaId, second: ParaId, removed_second: Arc<ParaShell> },
    // блоки / blocks
    InsertBlock { parent: ContainerRef, index: u32, block: Arc<Block> },
    RemoveBlock { parent: ContainerRef, index: u32, block: Arc<Block> },
    MoveBlocks { from: (ContainerRef, Range<u32>), to: (ContainerRef, u32) },
    // таблицы / tables
    InsertRow { table: TableId, index: u16, row: Arc<TableRow> }, RemoveRow { .. },
    InsertColumn { table: TableId, grid_index: u16, width: Twips, cells: Arc<[TableCell]> }, RemoveColumn { .. },
    MergeCells { table: TableId, rect: CellRect, prev: Arc<CellsSnapshot> }, SplitCell { .. },
    SetTableProps { .. }, SetRowProps { .. }, SetCellProps { .. }, SetTableGrid { table: TableId, new: Arc<[Twips]>, prev: Arc<[Twips]> },
    // разделы, объекты, поля, заметки, закладки, комментарии / sections, objects, fields, notes, bookmarks, comments
    SetSectionProps { section: NodeId, new: Arc<SectionProps>, prev: Arc<SectionProps> },
    InsertSection { index: u16, section: Arc<Section> }, RemoveSection { .. },
    SetHeaderFooter { section: NodeId, slot: HfSlot, new: Option<Arc<BlockList>>, prev: Option<Arc<BlockList>> },
    InsertObject { object: Arc<DrawingObject> }, RemoveObject { .. }, SetObjectProps { id: ObjectId, patch: ObjectPatch, prev: Arc<ObjectPatch> },
    SetField { id: FieldId, new: Arc<Field>, prev: Option<Arc<Field>> }, RemoveField { .. },
    InsertNote { id: NoteId, body: Arc<BlockList>, kind: NoteKind }, RemoveNote { .. },
    SetBookmark { id: BookmarkId, new: Option<Arc<Bookmark>>, prev: Option<Arc<Bookmark>> },
    SetComment { id: CommentId, new: Option<Arc<Comment>>, prev: Option<Arc<Comment>> },
    // стили, нумерация, настройки / styles, numbering, settings
    SetStyle { id: StyleId, new: Option<Arc<Style>>, prev: Option<Arc<Style>> },
    SetDocDefaults { .. }, SetNumbering { id: NumId, new: Option<Arc<NumInstance>>, prev: .. }, SetAbstractNum { .. },
    SetSettings { patch: SettingsPatch, prev: SettingsPatch }, SetMeta { .. },
    // составные (раскрываются в примитивы при применении, хранятся для метки undo) / composite
    AcceptRevision { id: RevId }, RejectRevision { id: RevId },
}

pub struct Transaction {
    pub id: TxId, pub label: Cow<'static, str>,   // «Ввод текста», «Вставка таблицы» / undo label
    pub ops: Vec<Op>, pub time: Timestamp, pub author: AuthorId,
    pub coalesce: Option<CoalesceKey>,            // (para, kind) — слияние набора текста / typing coalescing
    pub selection_before: SelectionSnapshot, pub selection_after: SelectionSnapshot,
}

pub trait Apply { fn apply(&mut self, op: &Op) -> Result<(), ModelError>; fn invert(op: &Op) -> Op; }

pub struct SubDocument { pub id: NodeId, pub path: RelPath, pub locked: bool, pub expanded: bool,
                         pub range: (ParaId, ParaId), pub last_hash: Blake3Hash }

pub struct Item { pub range: Range<u32>, pub font: FontId, pub script: Script, pub lang: Lang,
                  pub level: u8, pub props: ResolvedCharId, pub kind: ItemKind } // Text | Tab | Object | Marker
pub struct ShapedRun { pub item: u32, pub glyphs: Vec<Glyph>, pub clusters: Vec<u32> /* glyph→char */,
                       pub advances: Vec<Lu>, pub offsets: Vec<(Lu, Lu)>, pub width: Lu, pub rtl: bool }
pub struct LineBox { pub y: Lu, pub height: Lu, pub ascent: Lu, pub x: Lu, pub width: Lu,
                     pub text_range: Range<u32>, pub visual: Vec<VisualRun>, pub justify_extra: Lu,
                     pub segment: u8 /* индекс сегмента обтекания */, pub trailing_ws: Lu }
pub struct ParagraphLayout { pub para: ParaId, pub width: Lu, pub lines: Vec<LineBox>, pub height: Lu,
                             pub label: Option<LabelBox>, pub fingerprint: u64 }

/// Разбить абзац на участки с постоянными (шрифт, письменность, направление, язык, свойства).
/// Split paragraph into runs of constant (font, script, direction, language, props).
fn itemize(p: &Paragraph, cx: &LayoutCtx) -> Vec<Item> {
    let text = p.text.as_str();
    let levels = bidi_levels(text, para_direction(p, cx));                  // 5.3
    let mut out = Vec::new();
    for (range, props_id) in p.runs.iter(0..p.text.len()) {                 // спаны прямого форматирования
        let props = cx.styles.resolve_char(cx, p, props_id);
        // Письменность: UAX #24 + разрешение Common/Inherited по соседям / script resolution
        for (srange, script) in script_runs(&text[range.clone()]) {
            // Выбор шрифта по письменности как в Word: ascii / hAnsi / eastAsia / cs по правилам
            // «hint», с резервом через fontdb fallback (Noto) по покрытию символов
            for (frange, font) in font_runs(&text[srange.clone()], props.font_for(script), cx.fonts) {
                for (lrange, level) in level_runs(&levels[frange.clone()]) {
                    out.push(Item { range: lrange, font, script, lang: props.lang_for(script),
                                    level, props: props.id(), kind: ItemKind::Text });
                }
            }
        }
    }
    split_at_markers_and_tabs(&mut out, &p.markers, text);  // '\t', U+FFFC → отдельные Item
    out
}

fn shape(item: &Item, text: &str, cx: &LayoutCtx) -> Arc<ShapedRun> {
    let key = ShapeKey { font: item.font, size: props.size, script: item.script, lang: item.lang,
                         rtl: item.level & 1 == 1, features: props.ot_features, text_hash: hash(&text[item.range]) };
    cx.shape_cache.get_or_insert(key, || {
        let mut buf = rustybuzz::UnicodeBuffer::new();
        buf.push_str(&text[item.range.clone()]);
        buf.set_direction(if key.rtl { RTL } else { LTR }); buf.set_script(item.script); buf.set_language(item.lang);
        let features = word_features(&props);   // kern=1 если kern>0 и размер ≥ порога; liga по умолчанию как Word:
                                                 // 'liga' вкл для шрифтов с настройкой ligatures, 'clig' — по OpenType-опции
        let out = rustybuzz::shape(cx.fonts.face(item.font), &features, buf);
        Arc::new(ShapedRun::from_hb(out, item, scale_to_lu(props.size)))
    })
}

fn break_lines_greedy(items: &[MeasuredItem], opps: &[BreakOpp], segs: &SegmentProvider, hy: &Hyphenator) -> Vec<LineBox> {
    let mut lines = vec![]; let mut start = 0; let mut y = Lu(0);
    while start < items.total_chars() {
        let seg = segs.segment_for(y, lines.len() == 0);       // 5.11: ширина строки с учётом обтекания
        let avail = seg.width - first_line_indent_if(lines.is_empty()) - right_indent;
        let mut last_ok: Option<BreakOpp> = None; let mut w = Lu(0);
        for opp in opps.iter_from(start) {
            // ширина до кандидата без концевых пробелов / width up to candidate, trailing whitespace excluded
            let (w_to, trailing) = measure(start..opp.pos, items);
            if w_to <= avail || last_ok.is_none() && opp.is_mandatory_fallback() { last_ok = Some(*opp); w = w_to; }
            if w_to > avail { break; }
            if opp.mandatory { break; }
        }
        let brk = match last_ok {
            Some(b) => b,
            None => emergency_break(start, avail, items)            // слово шире строки → разрыв по графемам (как Word)
        };
        if brk.hyphen { /* перешейпить хвост с '-' / reshape tail with hyphen */ }
        lines.push(make_line(start..brk.pos, seg, w, trailing_ws(start..brk.pos)));
        y += lines.last().height; start = brk.pos_after();       // пробелы после разрыва «съедаются» в trailing
    }
    lines
}

struct Node { pos: u32, kind: Kind /* Box(w) | Glue(w, stretch, shrink) | Penalty(w, p, flagged) */ }

fn break_lines_kp(nodes: &[Node], widths: &dyn Fn(usize /*line idx*/) -> Lu, tol: f32, params: &KpParams) -> Vec<usize> {
    // Три прохода как в TeX: 1) без переносов, tol = 1; 2) с переносами, tol = params.tolerance (2..4);
    // 3) emergency_stretch. Активные узлы: список кандидатов начала строки с (demerits, fitness, line).
    let mut active = vec![Active { at: 0, line: 0, demerits: 0.0, fitness: Fit::Normal, prev: None }];
    for (i, n) in nodes.iter().enumerate() {
        if !n.is_legal_break() { continue; }
        let mut candidates: [Option<Active>; 4] = Default::default();
        active.retain(|a| {
            let (w, st, sh) = sum_between(nodes, a.at, i);
            let r = adjustment_ratio(w, st, sh, widths(a.line));          // (W − w)/stretch или /shrink
            if r < -1.0 || n.is_forced() { return false; }               // строка не влезает → узел мёртв
            if r <= tol {
                let badness = 100.0 * r.abs().powi(3);
                let d = demerits(badness, n.penalty(), a, n.flagged, params); // + штраф за два переноса подряд,
                                                                               // + за смену класса fitness
                let fit = Fit::from_ratio(r);
                if candidates[fit as usize].map_or(true, |c| d < c.demerits) {
                    candidates[fit as usize] = Some(Active { at: i, line: a.line + 1, demerits: d, fitness: fit, prev: Some(a.clone_ref()) });
                }
            }
            true
        });
        active.extend(candidates.into_iter().flatten());
        if active.is_empty() { active.push(emergency_restart(i)); }     // как TeX: «Overfull», ставим разрыв здесь
    }
    backtrace(active.iter().min_by(|a, b| a.demerits.total_cmp(&b.demerits)).unwrap())
}

fn tab_advance(x: Lu, stops: &TabStops, default: Lu, avail: Lu, next_text_width: Lu, kind_override: Option<TabKind>) -> (Lu, TabFill) {
    // Позиции стопов — от левого края абзаца (Word: от левого отступа; при compat-флаге — от поля).
    match stops.next_after(x) {
        Some(stop) => match stop.kind {
            Left    => (stop.pos - x, stop.leader),
            Center  => (stop.pos - x - next_text_width / 2, stop.leader),
            Right   => (stop.pos - x - next_text_width, stop.leader),       // next_text_width — до следующей табуляции/конца
            Decimal => (stop.pos - x - width_before_decimal_sep(next_text), stop.leader),
            Bar     => (Lu(0), TabFill::Bar(stop.pos)),                      // черта, позиция не меняется
        },
        None => { let n = ((x / default) + 1) * default; if n > avail { (Lu(0), TabFill::None) /* перенос строки */ } else { (n - x, TabFill::None) } }
    }
}

fn line_height(line: &LineRuns, sp: &ParaSpacing, grid: Option<&DocGrid>) -> (Lu /*height*/, Lu /*ascent*/) {
    // natural: max по run'ам (ascent_i, descent_i) с метриками «как Word» / Word-like font metrics
    let (asc, desc) = line.runs.iter().fold((Lu(0), Lu(0)), |(a, d), r| {
        let m = word_metrics(r.font, r.size);  // asc = usWinAscent, desc = usWinDescent (+ external leading:
                                               // max(0, hhea.asc + |hhea.desc| + hhea.lineGap − (winAsc + winDesc)) делится
                                               // как у GDI; при fsSelection.USE_TYPO_METRICS — typo-метрики)
        (a.max(m.ascent + r.raise), d.max(m.descent + m.ext_leading - r.raise))
    });
    let natural = asc + desc;
    let (h, a) = match sp.line_rule {
        LineRule::Auto    => { let h = natural * sp.line / 240; (h, asc + (h - natural) /* доп. интервал Word кладёт сверху */) },
        LineRule::AtLeast => if sp.line > natural { (sp.line, asc + (sp.line - natural)) } else { (natural, asc) },
        LineRule::Exact   => (sp.line, asc - (natural - sp.line).max(Lu(0)) * asc / natural.max(Lu(1))), // обрезка сверху/снизу пропорционально
    };
    match grid { Some(g) if g.snap_lines() => snap_to_pitch(h, a, g.line_pitch), _ => (h, a) }
}

struct FlowState { page: u32, column: u8, y: Lu, col_rect: Rect, floats: FloatSet, fn_reserve: Lu,
                   pending_keep: Vec<BlockRef> /* цепочка keep_with_next */, line_no: u32, num_state: NumState }

fn flow_section(sec: &Section, st: &mut FlowState, out: &mut Pages, cache: &LayoutCache) -> Result<(), Cancelled> {
    for block in sec.blocks.iter() {
        match block {
            Block::Paragraph(p) => flow_paragraph(p, st, out, cache)?,
            Block::Table(t)     => flow_table(t, st, out, cache)?,          // 5.12
            Block::Sdt(s)       => flow_blocks(&s.blocks, st, out, cache)?,
        }
    }
    if sec.props.break_kind == Continuous { balance_columns(st, out); }        // как Word: уравнять колонки
    finish_section(st, out, sec.props.break_kind);                              // Even/OddPage → пустая страница
    Ok(())
}

fn flow_paragraph(p: &Paragraph, st: &mut FlowState, out: &mut Pages, cache: &LayoutCache) -> Result<(), Cancelled> {
    let props = resolve_para(p);
    if props.page_break_before || has_marker(p, Break::Page) && at_start(p) { new_page(st, out); }
    place_anchored_objects_of(p, st, out);                                      // 5.11, до раскладки строк
    let pl = cache.layout_paragraph(p, SegmentProvider::new(st), /*first_line_y*/ st.y)?;  // строки с учётом обтекания
    let space_before = if st.at_top_of_column() && st.auto_break_here && !first_in_section { Lu(0) } else { props.spacing.before };
    let mut lines = pl.lines.as_slice();
    // Разбиение абзаца по страницам с учётом keep_lines / widow_control / keep_next
    loop {
        let avail = st.col_rect.bottom() - st.y - st.fn_reserve;
        let fits = count_lines_that_fit(lines, avail - space_before, &st.footnotes_for(lines));
        let total = lines.len();
        let (take, action) = decide_split(fits, total, &props, st);
        match action {
            Split::All => { emit(lines, st); break; }
            Split::MoveWhole => { new_column_or_page(st, out); continue; }   // не влезает ни одна строка/keep_lines
            Split::Partial(n) => { emit(&lines[..n], st); lines = &lines[n..]; new_column_or_page(st, out); }
        }
    }
    if props.keep_next { st.pending_keep.push(p.into()); } else { st.pending_keep.clear(); }
    Ok(())
}

fn decide_split(fits: usize, total: usize, pr: &ResolvedPara, st: &FlowState) -> (usize, Split) {
    if fits >= total { return (total, Split::All); }
    if pr.keep_lines || fits == 0 { return (0, Split::MoveWhole); }
    let mut n = fits;
    if pr.widow_control { if n < 2 { return (0, Split::MoveWhole); } if total - n < 2 { n = total - 2; } if n < 2 { return (0, Split::MoveWhole); } }
    (n, Split::Partial(n))
}

struct FloatSet { items: Vec<PlacedFloat> }           // на страницу: прямоугольник/контур + wrap + z
struct PlacedFloat { id: ObjectId, bbox: Rect, wrap: Wrap, exclusion: Exclusion /* Rect | Polygon */ }

/// Свободные сегменты строки высотой [y0, y1) внутри колонки. / Free segments for a line band.
fn free_segments(col: &Rect, y0: Lu, y1: Lu, floats: &FloatSet, min_w: Lu) -> SmallVec<[Segment; 4]> {
    let mut blocked: SmallVec<[(Lu, Lu); 8]> = SmallVec::new();
    for f in &floats.items {
        if f.bbox.bottom <= y0 || f.bbox.top >= y1 { continue; }
        match (&f.wrap, &f.exclusion) {
            (Wrap::None { .. }, _) => continue,
            (Wrap::TopAndBottom, _) => return smallvec![],                       // строка пропускается, y → bbox.bottom
            (Wrap::Square { sides }, Exclusion::Rect(r)) => push_sides(&mut blocked, r.left, r.right, sides, col),
            (Wrap::Tight { sides, .. }, Exclusion::Polygon(poly)) => {
                // пересечение полосы [y0,y1) с полигоном: min/max x по всем рёбрам, попадающим в полосу
                let (l, r) = poly.x_extent_in_band(y0, y1);
                push_sides(&mut blocked, l - f.dist.left, r + f.dist.right, sides, col);
            }
            (Wrap::Through { sides, .. }, Exclusion::Polygon(poly)) => {
                for (l, r) in poly.x_intervals_in_band(y0, y1) { push_sides(&mut blocked, l, r, sides, col); } // дырки допустимы
            }
            _ => unreachable!(),
        }
    }
    blocked.sort_by_key(|b| b.0); merge_overlapping(&mut blocked);
    complement(col.left, col.right, &blocked).into_iter().filter(|s| s.width() >= min_w).collect()
}