{"record":{"id":"736f39f352ee9908","repo":"tui-cs/Terminal.Gui","slug":"the-first-item-must-be-the-original","errorCode":null,"errorMessage":"The first item must be the original.","messagePattern":"The first item must be the original\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"Terminal.Gui/Views/TextInput/HistoryText.cs","lineNumber":29,"sourceCode":"    public void Add (List<List<Cell>> lines, Point curPos, TextEditingLineStatus lineStatus = TextEditingLineStatus.Original)\n    {\n        if (lineStatus == TextEditingLineStatus.Original\n            && _historyTextItems.Count > 0\n            && _historyTextItems.Last ().LineStatus == TextEditingLineStatus.Original)\n        {\n            return;\n        }\n\n        if (lineStatus == TextEditingLineStatus.Replaced\n            && _historyTextItems.Count > 0\n            && _historyTextItems.Last ().LineStatus == TextEditingLineStatus.Replaced)\n        {\n            return;\n        }\n\n        if (_historyTextItems.Count == 0 && lineStatus != TextEditingLineStatus.Original)\n        {\n            throw new ArgumentException (\"The first item must be the original.\");\n        }\n\n        if (_idxHistoryText >= 0 && _idxHistoryText + 1 < _historyTextItems.Count)\n        {\n            _historyTextItems.RemoveRange (_idxHistoryText + 1, _historyTextItems.Count - _idxHistoryText - 1);\n        }\n\n        _historyTextItems.Add (new HistoryTextItemEventArgs (lines, curPos, lineStatus));\n        _idxHistoryText++;\n    }\n\n    public event EventHandler<HistoryTextItemEventArgs?>? ChangeText;\n\n    public void Clear (List<List<Cell>> cellsList)\n    {\n        _historyTextItems.Clear ();\n        _idxHistoryText = -1;\n        _originalCellsList.Clear ();","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/tui-cs/Terminal.Gui/blob/2e47b11478db083499917f2ad27c34d30efb0df1/Terminal.Gui/Views/TextInput/HistoryText.cs#L11-L47","documentation":"Thrown by HistoryText.Add when the items collection is empty and the incoming lineStatus is not Original. HistoryText models an undo stack whose first entry must be the baseline 'Original' content; any later edit (Added/Removed/Replaced/etc.) is only valid on top of an existing baseline. Enforcing this keeps the undo/redo invariant that there is always something to revert to.","triggerScenarios":"Calling HistoryText.Add with a non-Original status before ever adding an Original entry — e.g. recording an edit before initialising history with the document's original lines, or after history was cleared and an edit arrives first.","commonSituations":"TextView/Editor integration that begins tracking edits before seeding the original text; clearing _historyTextItems then receiving an edit before re-seeding; a copy/replay of history items that omits the leading Original.","solutions":["Always seed history with the original content first: history.Add(originalLines, cursorPos, TextEditingLineStatus.Original);","After clearing history, immediately re-add the current text as Original before recording further edits.","When replaying/snapshotting, ensure the first element carried over is marked Original."],"exampleFix":"// before\nhistory.Add(editedLines, pos, TextEditingLineStatus.Added); // empty history -> throws 174\n\n// after\nhistory.Add(currentLines, pos, TextEditingLineStatus.Original);\nhistory.Add(editedLines, pos, TextEditingLineStatus.Added);","handlingStrategy":"validation","validationCode":"if (history is not seeded)\n{\n    history.Add(currentLines, pos, TextEditingLineStatus.Original);\n}\nhistory.Add(editedLines, pos, status);","typeGuard":"static bool HistoryHasBaseline(HistoryText h) => /* expose whether first item is Original */ true;","tryCatchPattern":null,"preventionTips":["Always seed history with Original before recording edits.","After clearing history, re-seed with current content immediately.","When replaying snapshots, preserve the leading Original entry."],"tags":["historytext","textinput","state","precondition"],"backgroundTag":null,"analyzedSha":"2e47b11478db083499917f2ad27c34d30efb0df1","analyzedAt":"2026-08-13T19:20:08.826Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}