Streaming reduction and UI projection

fn new() -> Self

Purpose: Creates a fresh citation parser that knows the exact opening and closing citation tags. Use this when starting to read a new piece of text or a new stream of text.

Data flow: It takes no caller-provided data. It builds one tag rule using <oai-mem-citation> as the start marker and </oai-mem-citation> as the end marker, gives that rule to the general hidden-tag parser, and returns a ready-to-use CitationStreamParser with empty internal state.

Call relations: This is the setup step for the parser. strip_citations calls it when cleaning a complete string, and the tests call it to check streaming behavior, unfinished tags, and partial tag prefixes. Internally it hands the tag rule to InlineHiddenTagParser::new, which does the lower-level scanning work.

Call graph: calls 1 internal fn (new); called by 11 (strip_citations, citation_parser_auto_closes_unterminated_tag_on_finish, citation_parser_buffers_partial_open_tag_prefix, citation_parser_preserves_partial_open_tag_at_eof_if_not_a_full_tag, citation_parser_streams_across_chunk_boundaries, utf8_stream_parser_errors_on_incomplete_code_point_at_eof, utf8_stream_parser_handles_split_code_points_across_chunks, utf8_stream_parser_into_inner_errors_when_partial_code_point_is_buffered, utf8_stream_parser_into_inner_lossy_drops_buffered_partial_code_point, utf8_stream_parser_rolls_back_entire_chunk_when_invalid_byte_follows_valid_prefix (+1 more)); 1 external calls (vec!).

fn default() -> Self

Purpose: Provides the standard default way to make a citation parser. It exists so code that expects a Default value can create this parser without spelling out new.

Data flow: It receives no input, calls the parser constructor, and returns the same kind of empty, ready-to-use citation parser that CitationStreamParser::new returns.

Call relations: This is a convenience doorway into CitationStreamParser::new. The test helper uses default construction for generic parser setup, and any outside code using Rust's Default pattern can do the same.

Call graph: 1 external calls (new).

fn push_str(&mut self, chunk: &str) -> StreamTextChunk<Self::Extracted>

Purpose: Feeds one new piece of text into the citation parser. It returns the visible text that is safe to show now, plus any complete citation bodies found in that piece and any buffered earlier pieces.

Data flow: It receives a text chunk and the parser's current saved state. It passes the chunk to the inner hidden-tag parser, then converts the inner extracted tag records into plain strings by keeping only each tag's content. It returns a StreamTextChunk containing visible text and extracted citation strings, while the parser keeps any unfinished tag fragments for later chunks.

Call relations: This is the main streaming entry point. Callers repeatedly use it as text arrives. It delegates the hard part, such as recognizing tags split across chunk boundaries, to the inner parser, then reshapes the result into the citation-specific output type.

Call graph: calls 1 internal fn (push_str); called by 1 (push_str).

fn finish(&mut self) -> StreamTextChunk<Self::Extracted>

Purpose: Tells the parser that no more text is coming. It flushes any saved text and, if a citation was opened but never closed, returns that unfinished citation body as an extracted citation.

Data flow: It reads the parser's internal buffered state and asks the inner parser to finish. It then keeps the visible leftover text and turns any extracted tag records into plain citation strings. The result is a final StreamTextChunk; after this, the stream is considered complete.

Call relations: This is called after the last push_str. strip_citations uses it after feeding the whole input, and the test helper uses it after all test chunks. It relies on the inner parser's finishing behavior, including auto-closing an unterminated citation at end of input.

Call graph: calls 1 internal fn (finish); called by 1 (finish).

fn strip_citations(text: &str) -> (String, Vec<String>)

Purpose: Removes citation tags from a complete string in one call and returns both the cleaned text and the collected citations. It is the simple non-streaming helper for callers that already have all the text.

Data flow: It takes one full text string. It creates a CitationStreamParser, pushes the whole string into it, then calls finish to flush anything left. It joins the visible text from both steps, combines the extracted citations, and returns them as (visible_text, citations).

Call relations: This function packages the streaming parser into an easier one-shot API. Tests use it to check multiple citations, unfinished citations at the end of the string, and the important rule that nested citation tags are not specially supported.

Call graph: calls 1 internal fn (new); called by 3 (citation_parser_does_not_support_nested_tags, strip_citations_auto_closes_unterminated_citation_at_eof, strip_citations_collects_all_citations).

fn collect_chunks(parser: &mut P, chunks: &[&str]) -> StreamTextChunk<P::Extracted>

Purpose: Helps tests feed a parser several chunks and collect all visible text and extracted items into one result. It makes streaming tests easier to read.

Data flow: It receives a mutable parser and a list of text chunks. For each chunk it calls push_str, appends the returned visible text, and adds the returned extracted items. At the end it calls finish and appends that final output too, then returns the combined StreamTextChunk.

Call relations: The streaming-focused tests call this helper so they can describe input as several pieces and then assert on one combined result. It uses the general StreamTextParser trait, so it is not tied only to citation parsing.

Call graph: calls 1 internal fn (default); 2 external calls (finish, push_str).

fn citation_parser_streams_across_chunk_boundaries()

Purpose: Checks that citation tags are still recognized when the tag text is split across incoming chunks. This protects the main streaming use case.

Data flow: It creates a new parser and feeds three chunks where both the opening and closing citation tags are divided across chunk boundaries. It expects the visible output to contain only Hello world and the extracted citations to contain source A.

Call relations: This test uses CitationStreamParser::new and the shared tests::collect_chunks helper. It proves that the parser and its inner hidden-tag scanner work like a reader holding a bookmark between pages, remembering partial tag text until the next chunk arrives.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, collect_chunks).

fn citation_parser_buffers_partial_open_tag_prefix()

Purpose: Checks that a possible opening tag prefix is held back until the parser can tell whether it is really a citation tag. This prevents half a tag from leaking into visible text too early.

Data flow: It creates a parser and first pushes abc <oai-mem-, which might be the start of a citation tag. The parser returns only abc as visible text and no citation. Then it pushes the rest of the tag, citation body, close tag, and trailing z; the parser returns z as visible text and x as the extracted citation, and finishing returns nothing extra.

Call relations: This test calls the parser directly rather than using the helper, because it needs to inspect the result after the first chunk. It checks the buffering behavior supplied through CitationStreamParser::push_str and completed by finish.

Call graph: calls 1 internal fn (new); 2 external calls (assert!, assert_eq!).

fn citation_parser_auto_closes_unterminated_tag_on_finish()

Purpose: Checks that an open citation is still returned when the input ends without a closing citation tag. This confirms the parser does not silently lose citation information at end of stream.

Data flow: It feeds text containing x followed by an opening citation tag and the body source, but no closing tag. After finishing, the combined visible text is x and the extracted citation list contains source.

Call relations: This test uses CitationStreamParser::new and tests::collect_chunks. It focuses on the behavior of CitationStreamParser::finish, which asks the inner parser to close out any still-open hidden tag.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, collect_chunks).

fn citation_parser_preserves_partial_open_tag_at_eof_if_not_a_full_tag()

Purpose: Checks that a mere prefix of a citation tag is not treated as a real hidden citation when the input ends. This keeps ordinary text from disappearing just because it looks like the start of a tag.

Data flow: It feeds hello <oai-mem-, which is only part of the citation opening marker. When the stream finishes, the parser returns that whole text as visible output and extracts no citations.

Call relations: This test uses CitationStreamParser::new and tests::collect_chunks. It complements the unfinished-citation test by showing that auto-closing only happens after a full opening tag has actually been seen.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, collect_chunks).

fn strip_citations_collects_all_citations()

Purpose: Checks that the one-shot helper removes more than one citation tag and returns all citation bodies in order. This protects the simple API used for complete strings.

Data flow: It passes a complete string with visible letters around two citation tags. strip_citations returns abc as the visible text and the two citation bodies, one and two, as a list.

Call relations: This test calls strip_citations, which in turn creates and uses CitationStreamParser. It confirms that the wrapper around the streaming parser preserves all extracted citations rather than only the first one.

Call graph: calls 1 internal fn (strip_citations); 1 external calls (assert_eq!).

fn strip_citations_auto_closes_unterminated_citation_at_eof()

Purpose: Checks that the one-shot helper has the same end-of-input behavior as the streaming parser for an unfinished citation. This keeps the two APIs consistent.

Data flow: It passes x<oai-mem-citation>y to strip_citations. The function returns x as visible text and y as the extracted citation, even though no closing citation tag appears.

Call relations: This test calls strip_citations, which relies on CitationStreamParser::finish after pushing the input. It verifies that the helper inherits the parser's auto-close rule.

Call graph: calls 1 internal fn (strip_citations); 1 external calls (assert_eq!).

fn citation_parser_does_not_support_nested_tags()

Purpose: Documents and checks the rule that citation tags are not nested. The parser stops at the first closing tag it sees, even if another opening tag appeared inside the citation body.

Data flow: It passes text with a citation opening tag inside another citation. The parser treats the inner opening tag as ordinary citation-body text, extracts x<oai-mem-citation>y, and leaves the later outer closing tag visible as plain text, producing az</oai-mem-citation>b.

Call relations: This test calls strip_citations to exercise the public one-shot API. It captures an important limitation of the underlying literal scanner so future changes do not accidentally change how nested-looking input is interpreted.

Call graph: calls 1 internal fn (strip_citations); 1 external calls (assert_eq!).

fn new() -> Self

Purpose: Creates a parser that specifically looks for <proposed_plan> blocks. Use this when starting to process a fresh assistant message or text stream.

Data flow: It takes no outside input. It builds a TaggedLineParser configured with one rule: the opening plan tag, the closing plan tag, and the internal label meaning “this is a proposed plan.” It returns a ready-to-use ProposedPlanParser with empty parsing state.

Call relations: This is the starting point for the rest of the file. The stripping and extraction helpers call it before parsing full text, and the tests call it before feeding sample chunks. It hands the tag setup to TaggedLineParser::new, which does the lower-level work of recognizing tagged blocks.

Call graph: calls 1 internal fn (new); called by 5 (extract_proposed_plan_text, strip_proposed_plan_blocks, closes_unterminated_plan_block_on_finish, preserves_non_tag_lines, streams_proposed_plan_segments_and_visible_text); 1 external calls (vec!).

fn default() -> Self

Purpose: Provides the standard default way to create a ProposedPlanParser. This lets other Rust code use default construction without needing to remember the exact setup.

Data flow: It receives no data. It simply delegates to ProposedPlanParser::new, so the result is the same freshly configured parser.

Call relations: This is a convenience wrapper around ProposedPlanParser::new. Any caller that asks for the default parser gets the same tag-aware parser used everywhere else in this file.

Call graph: 1 external calls (new).

fn push_str(&mut self, chunk: &str) -> StreamTextChunk<Self::Extracted>

Purpose: Feeds one new piece of streamed text into the parser. It returns what can be shown immediately and what plan-related pieces were found.

Data flow: It receives a text chunk and reads the parser’s current internal state, which may include a partly seen tag from earlier chunks. It asks the underlying tagged-line parser to parse the new text, then converts the generic tag results into ProposedPlanSegment values. It returns a StreamTextChunk containing visible normal text and extracted plan events.

Call relations: This is the main streaming entry point through the StreamTextParser trait. Higher-level parsing code calls it whenever more text arrives. It relies on the lower-level parse method to find tag boundaries, then hands those raw segments to map_segments so callers see proposed-plan-specific results.

Call graph: calls 2 internal fn (map_segments, parse); called by 1 (parse_visible_text).

fn finish(&mut self) -> StreamTextChunk<Self::Extracted>

Purpose: Ends parsing and flushes any leftover text or unfinished plan block. Call this when no more stream chunks are coming.

Data flow: It takes no new text, but reads the parser’s saved state. It asks the underlying parser to finish, which may produce final normal text or close an open plan block. It maps those final generic segments into proposed-plan segments and returns them in a StreamTextChunk.

Call relations: This completes the same flow started by push_str. Trait users call it at the end of a stream, and it passes final raw parser output through map_segments so the last pieces have the same shape as earlier streamed pieces.

Call graph: calls 2 internal fn (map_segments, finish); called by 1 (finish).

fn map_segments(segments: Vec<TaggedLineSegment<PlanTag>>) -> StreamTextChunk<ProposedPlanSegment>

Purpose: Converts generic tagged parser output into the specific language of proposed-plan parsing. It also decides which text remains visible to the user.

Data flow: It receives a list of generic TaggedLineSegment values. For each one, it turns normal text into ProposedPlanSegment::Normal, tag openings into ProposedPlanStart, plan body text into ProposedPlanDelta, and tag endings into ProposedPlanEnd. Normal text is appended to visible_text; every mapped segment is appended to extracted. It returns the completed StreamTextChunk.

Call relations: push_str and finish both call this after the lower-level tagged parser has done its work. It is the bridge between the generic tag-finding machinery and the public proposed-plan API.

Call graph: calls 1 internal fn (default); called by 2 (finish, push_str); 2 external calls (Normal, ProposedPlanDelta).

fn strip_proposed_plan_blocks(text: &str) -> String

Purpose: Removes proposed-plan blocks from a complete string and returns only the text that should be visible. This is useful when the caller does not need streaming events, just cleaned text.

Data flow: It receives a whole text string. It creates a new parser, pushes the whole string through it, then finishes the parser to collect any final visible text. It returns the combined visible text, with plan blocks left out.

Call relations: This helper uses ProposedPlanParser::new and the parser’s streaming methods internally, but hides that process from callers. It is a simpler one-shot path for code that only wants to display or store text without proposed-plan content.

Call graph: calls 1 internal fn (new).

fn extract_proposed_plan_text(text: &str) -> Option<String>

Purpose: Pulls the text inside a proposed-plan block from a complete string. It returns None if no plan block was found.

Data flow: It receives a whole text string. It creates a parser, parses the string, finishes parsing, and walks through all extracted segments in order. When it sees a plan start, it records that a plan exists and clears the collected text. When it sees plan text deltas, it appends them. At the end, it returns the collected plan text if any plan block was seen.

Call relations: This is the one-shot extraction companion to strip_proposed_plan_blocks. It uses ProposedPlanParser::new and the same stream parsing path, then interprets the resulting ProposedPlanSegment events to produce a plain Option<String> for callers.

Call graph: calls 1 internal fn (new); 1 external calls (new).

fn collect_chunks(parser: &mut P, chunks: &[&str]) -> StreamTextChunk<P::Extracted>

Purpose: Test helper that feeds several text chunks into a stream parser and gathers all results into one combined output. It keeps the tests focused on expected behavior instead of repeated setup code.

Data flow: It receives a mutable parser and a list of string chunks. For each chunk, it calls push_str, appends the visible text, and extends the extracted segment list. After all chunks are sent, it calls finish and appends the final output. It returns one combined StreamTextChunk.

Call relations: The streaming tests call this helper to mimic real streamed input. It drives the parser the same way production code would: several push_str calls followed by one finish.

Call graph: calls 1 internal fn (default); 2 external calls (finish, push_str).

fn streams_proposed_plan_segments_and_visible_text()

Purpose: Checks that the parser correctly handles a proposed-plan tag split across multiple streamed chunks. It verifies both the hidden plan extraction and the visible text shown outside the plan.

Data flow: It creates a new parser and sends three chunks, including a split opening tag. It then compares the combined visible text and extracted segment list against the expected result: intro and outro remain visible, while the plan appears as start, delta, and end events.

Call relations: This test calls ProposedPlanParser::new and tests::collect_chunks. It proves that the main streaming path can survive chunk boundaries in awkward places, which is essential for real streamed assistant output.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, collect_chunks).

fn preserves_non_tag_lines()

Purpose: Checks that text which merely resembles a proposed-plan tag is not treated as a real tag unless it matches the expected tag line format.

Data flow: It creates a parser and feeds a line containing spaces and extra text around <proposed_plan>. The parser output is compared with the original line as normal visible text and a single normal extracted segment.

Call relations: This test uses ProposedPlanParser::new and tests::collect_chunks to guard against over-eager parsing. It makes sure ordinary user-visible text is not accidentally removed just because it contains tag-like characters.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, collect_chunks).

fn closes_unterminated_plan_block_on_finish()

Purpose: Checks what happens when a plan block starts but the closing tag never arrives. The expected behavior is that finishing the stream still produces a clean plan end event.

Data flow: It creates a parser, feeds an opening tag and plan text, then relies on finish through the helper. The visible text should be empty, and the extracted output should contain a plan start, the plan text, and a generated plan end.

Call relations: This test drives the normal streaming lifecycle through tests::collect_chunks. It confirms the contract of ProposedPlanParser::finish: callers do not have to handle dangling plan blocks themselves.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, collect_chunks).

fn strips_proposed_plan_blocks_from_text()

Purpose: Checks the one-shot helper that removes plan blocks from ordinary text. It verifies that only the before-and-after text remains.

Data flow: It builds a sample string with text before a plan block, plan content, and text after it. It calls strip_proposed_plan_blocks and compares the returned string with the expected visible text.

Call relations: This test exercises the convenience helper rather than the parser directly. It shows that strip_proposed_plan_blocks correctly uses the parser pipeline internally.

Call graph: 1 external calls (assert_eq!).

fn extracts_proposed_plan_text()

Purpose: Checks the one-shot helper that returns the text inside a proposed-plan block. It verifies that the helper ignores surrounding normal text.

Data flow: It builds a sample string containing one plan block. It calls extract_proposed_plan_text and compares the result with Some containing only the plan body.

Call relations: This test exercises the extraction helper from the outside, as a caller would use it. It confirms that the parser events are interpreted correctly into a simple optional string.

Call graph: 1 external calls (assert_eq!).

fn is_empty(&self) -> bool

Purpose: Checks whether a parsed chunk contains nothing useful: no text for the user, no citations, and no plan updates. This is helpful at the end of a stream, where finishing the parser may or may not produce one last piece of output.

Data flow: It reads the chunk’s three fields: visible_text, citations, and plan_segments. If all three are empty, it returns true; otherwise it returns false. It does not change the chunk.

Call relations: This is a simple question asked of an AssistantTextChunk after parsing. In this file, the plan-mode test uses it to confirm that calling finish after all text has already been parsed produces no extra output.

fn new(plan_mode: bool) -> Self

Purpose: Creates a fresh assistant-text parser and chooses whether proposed-plan parsing should be active. Use it when starting to read a new streamed assistant message.

Data flow: It takes one input, plan_mode, which says whether <proposed_plan> markup should be treated specially. It starts from the parser’s default empty state, stores that mode flag, and returns a ready-to-use AssistantTextStreamParser with fresh citation and plan parsers inside.

Call relations: The tests call this first to set up a parser before feeding it streamed text. Internally it relies on the default constructor for the rest of the fields, so the citation parser and plan parser both start with no remembered partial tag.

Call graph: called by 2 (parses_citations_across_seed_and_delta_boundaries, parses_plan_segments_after_citation_stripping); 1 external calls (default).

fn push_str(&mut self, chunk: &str) -> AssistantTextChunk

Purpose: Feeds one new piece of streamed assistant text into the parser and returns whatever can be safely emitted now. This is the main method used while a response is still arriving.

Data flow: It receives a text chunk. First, it passes that chunk to the citation parser, which removes citation tags from the text and collects completed citation payloads. Then it sends the cleaned visible text to parse_visible_text, which may also remove proposed-plan markup if plan mode is on. The returned AssistantTextChunk contains visible user-facing text, any citations completed by this input, and any plan segments completed by this input.

Call relations: This method is the streaming front door. It hands raw incoming text to the citation parser first, then calls AssistantTextStreamParser::parse_visible_text so plan parsing sees text after citations have already been stripped out.

Call graph: calls 2 internal fn (parse_visible_text, push_str).

fn finish(&mut self) -> AssistantTextChunk

Purpose: Tells the parser that no more text is coming and asks it to flush any leftover partial markup. This prevents unfinished buffered text from being silently dropped at the end of a stream.

Data flow: It first finishes the citation parser, receiving any final visible text and completed citations. It then sends that remaining visible text through parse_visible_text. If plan mode is active, it also finishes the plan parser and appends any final visible text or plan segments it produces. The result is one final AssistantTextChunk containing all remaining output.

Call relations: This is called after the last streamed chunk. It coordinates the citation parser’s finish, its own parse_visible_text, and, in plan mode, the proposed-plan parser’s finish, so each layer gets a chance to release text it was holding while waiting for a closing tag.

Call graph: calls 3 internal fn (parse_visible_text, finish, finish).

fn parse_visible_text(&mut self, visible_text: String) -> AssistantTextChunk

Purpose: Processes text after citations have already been removed. If proposed-plan parsing is off, it simply returns the text as visible output; if it is on, it separates normal visible text from proposed-plan segments.

Data flow: It receives a string that is already free of citation markup. When plan_mode is false, it places that string directly into an AssistantTextChunk. When plan_mode is true, it passes the string to the proposed-plan parser, then returns a chunk containing the parser’s visible text and extracted plan segments.

Call relations: push_str and finish both call this as the second parsing stage. It delegates to the proposed-plan parser only when plan mode is enabled; otherwise it avoids that extra interpretation and treats all citation-cleaned text as ordinary visible text.

Call graph: calls 1 internal fn (push_str); called by 2 (finish, push_str); 1 external calls (default).

fn parses_citations_across_seed_and_delta_boundaries()

Purpose: Checks that citation parsing still works when a citation tag is split across multiple streamed chunks. This protects against a common streaming problem where meaningful markup does not arrive all at once.

Data flow: The test creates a parser with plan mode turned off, feeds it text where the citation starts in one chunk and ends in the next, then finishes the stream. It expects the user-visible output to be hello followed later by world, while the citation payload doc1 is returned separately and not shown in the visible text.

Call relations: The test begins by calling AssistantTextStreamParser::new to create the parser. It then uses assertions to verify the parser’s public streaming behavior: partial citation text is remembered until the closing citation tag arrives, and finish adds nothing once all content has already been emitted.

Call graph: calls 1 internal fn (new); 1 external calls (assert_eq!).

fn parses_plan_segments_after_citation_stripping()

Purpose: Checks that proposed-plan parsing happens after citation removal, and that both features still work when tags are split across chunks. This makes sure plan text does not accidentally include citation markup.

Data flow: The test creates a parser with plan mode turned on, feeds it an intro, a split <proposed_plan> opening tag, a plan line containing a citation, a closing plan tag, and an outro. It expects normal text to remain visible, the citation doc to be extracted separately, and the plan parser to emit start, delta, end, and normal-text segments in the right order.

Call relations: The test calls AssistantTextStreamParser::new to start in plan mode, then uses equality and truth assertions to check the combined parser behavior. It exercises the intended pipeline: citation markup is removed first, then proposed-plan markup is interpreted from the cleaned text.

Call graph: calls 1 internal fn (new); 2 external calls (assert!, assert_eq!).

fn new() -> Self

Purpose: Creates a fresh table holdback scanner with no remembered source and no table detected yet. This is used when a stream starts, or when tests need a clean scanner.

Data flow: It takes no input. It builds a scanner whose source position starts at zero, whose fenced-code tracker is fresh, and whose previous-line, pending-header, and confirmed-table memory are empty. The result is a ready-to-use scanner waiting for source chunks.

Call relations: This is the starting point for the incremental scanner. The scanner’s reset path also returns to this same clean state, and tests create scanners this way when checking how table detection behaves across chunks.

Call graph: calls 1 internal fn (new); called by 3 (new, incremental_holdback_detects_header_delimiter_across_chunk_boundary, incremental_holdback_matches_stateless_scan_per_chunk).

fn reset(&mut self)

Purpose: Clears the scanner so it behaves like a brand-new one. Someone would use this when the current stream or accumulated source has been discarded and old table clues must not affect the next run.

Data flow: It takes the existing scanner as input by mutable reference. It replaces all remembered offsets, fence state, previous line state, and table state with the values from a new scanner. Afterward, the same scanner object is reused but contains no old history.

Call relations: This is a simple cleanup path. When called, it delegates the actual fresh-state construction to TableHoldbackScanner::new so reset and initial creation stay consistent.

Call graph: called by 1 (reset); 1 external calls (new).

fn state(&self) -> TableHoldbackState

Purpose: Reports the scanner’s current decision: no table, a possible header waiting for the next line, or a confirmed table whose start must stay mutable. The UI uses this answer to decide how much rendered output can safely move into stable scrollback.

Data flow: It reads the scanner’s stored table markers. If a confirmed table start exists, it returns that as the strongest answer. If not, but a pending header exists, it returns the header position. If neither exists, it returns that there is no table holdback needed.

Call relations: This is the scanner’s public status check. Code that budgets the active mutable tail asks for this state, while push_source_chunk updates the stored facts that state later reports.

Call graph: called by 1 (active_tail_budget_lines).

fn push_source_chunk(&mut self, source_chunk: &str)

Purpose: Feeds newly committed source text into the scanner. It is used as streaming output arrives, but only for source that is complete enough to inspect, usually whole lines rather than half-written table rows.

Data flow: It receives a text chunk. If the chunk is empty, nothing changes. Otherwise it splits the chunk into newline-ending pieces, sends each piece to push_line, counts how many lines it scanned, and writes a trace log with the byte count, line count, current state, and elapsed time. The scanner’s remembered position and table decision may change.

Call relations: This is the normal entry point for incremental scanning during streaming. The streaming collector calls it when pushing new deltas and when finalizing remaining text. It hands the detailed per-line work to TableHoldbackScanner::push_line.

Call graph: calls 1 internal fn (push_line); called by 2 (finalize_remaining, push_delta); 2 external calls (now, trace!).

fn push_line(&mut self, source_line: &str)

Purpose: Examines one committed source line and updates the scanner’s table detection memory. This is where a possible header becomes either a confirmed table or gets cleared when the next meaningful line does not match.

Data flow: It receives one source line, notes the line’s starting byte offset, and checks the current fenced-code context before advancing it. If the line is not in a non-Markdown code fence, it strips blockquote markers and checks whether the text looks like a table header or delimiter. If the previous line was a header and this line is a delimiter, it records a confirmed table starting at the previous line. If there is not yet a confirmed table, it records or clears a pending header based on the current non-blank line. Finally it saves this line as the previous line, advances the fence tracker, and moves the source offset forward by the line’s byte length.

Call relations: This is called only by TableHoldbackScanner::push_source_chunk as each line arrives. It relies on table_candidate_text to filter table-shaped lines and on the fence tracker to avoid false positives inside code blocks.

Call graph: calls 3 internal fn (table_candidate_text, advance, kind); called by 1 (push_source_chunk).

fn table_candidate_text(line: &str) -> Option<&str>

Purpose: Prepares a line for table detection and rejects lines that do not have a pipe-table shape. It lets quoted tables count as real tables by ignoring Markdown blockquote markers before checking the table structure.

Data flow: It receives one line of source text. It removes any leading blockquote prefix, trims surrounding whitespace, and asks the table parser whether pipe-separated table segments are present. If they are, it returns the cleaned text; otherwise it returns no value.

Call relations: Both the streaming scanner and the test-only full-source scanner use this helper before asking whether a line is a table header or delimiter. It keeps the quote-stripping and basic table-shape check in one place.

Call graph: calls 2 internal fn (parse_table_segments, strip_blockquote_prefix); called by 2 (push_line, table_holdback_state).

fn parse_lines_with_fence_state(source: &str) -> Vec<ParsedLine<'_>>

Purpose: In tests, breaks a source string into lines and labels each line with whether it was inside a fenced code block at that point. This helps the stateless test scanner compare its result with the incremental scanner.

Data flow: It receives a full source string. Starting at byte offset zero, it walks line by line, records the raw line text, the current fence context, and the line’s starting offset, then advances the fence tracker for the next line. It returns a list of these annotated lines.

Call relations: This function exists only for test builds. table_holdback_state calls it to get a complete, line-by-line view of source before looking for table header and delimiter pairs.

Call graph: calls 1 internal fn (new); called by 1 (table_holdback_state); 1 external calls (new).

fn table_holdback_state(source: &str) -> TableHoldbackState

Purpose: In tests, scans a whole source string at once and returns the same kind of holdback decision as the incremental scanner. It provides a simpler reference version that tests can compare against chunk-by-chunk streaming behavior.

Data flow: It receives full source text. It first parses lines with their fenced-code context. Then it looks at each neighboring pair of lines outside non-Markdown code fences; if one is a table header and the next is a delimiter, it returns a confirmed table starting at the header’s offset. If no confirmed table is found, it checks the last non-blank line and returns a pending header if that line looks like a table header. Otherwise it returns no holdback.

Call relations: This function is test-only support code. It uses parse_lines_with_fence_state and table_candidate_text to mirror the production scanner’s rules, then calls the header and delimiter checks to produce an expected state for tests.

Call graph: calls 4 internal fn (parse_lines_with_fence_state, table_candidate_text, is_table_delimiter_line, is_table_header_line).

fn should_render_records(
    rows: &[Vec<TableCell>],
    column_widths: &[usize],
    metrics: &[TableColumnMetrics],
) -> bool

Purpose: Decides whether a table should stop being shown as a grid and instead be shown as vertical records. It looks for signs that the grid layout has become unreadable, such as long tokens that do not fit or multiple wide-content cells being squeezed into tall wrapped blocks.

Data flow: It receives the table rows, the chosen width for each column, and measurements describing what kind of content each column has. It checks each row for cells that are likely to fragment badly or for non-compact cells that are starved for space. It returns true when enough rows are affected to justify switching to the vertical key/value layout; otherwise it returns false.

Call relations: The broader table renderer calls this before choosing how to draw a markdown table. If this function says the grid is no longer useful, the renderer can call render_records to draw the table in the more readable record style.

Call graph: called by 1 (render_table_lines).

fn expansive_cells_are_starved(
    row: &[TableCell],
    column_widths: &[usize],
    metrics: &[TableColumnMetrics],
) -> bool

Purpose: Checks whether a row has paragraph-like or otherwise roomy content that is being forced into columns too narrow to read comfortably. This catches cases where the problem is not one long word, but too much wrapping across several cells.

Data flow: It receives one row, the column widths, and the column metrics. It ignores compact columns, wraps each larger-content cell to its assigned width, and counts how many lines the cell would become. It returns true if several expansive cells become cramped, or if a narrative cell becomes especially narrow and tall.

Call relations: should_render_records uses this as one of its warning signs. It helps the decision step notice when the normal grid would produce tall, awkward strips of text rather than readable table cells.

Call graph: 1 external calls (iter).

fn render_records(
    headers: &[TableCell],
    rows: &[Vec<TableCell>],
    metrics: &[TableColumnMetrics],
    available_width: Option<usize>,
    label_style: Style,
    separator_style: Style,
)

Purpose: Renders the whole table as vertical records instead of as a grid. Each original row becomes a block of labeled fields, with a separator line between row blocks.

Data flow: It receives the headers, rows, column metrics, optional available terminal width, and styles for labels and separators. It calculates how wide labels are and decides whether labels and values can fit side by side. It then renders every header/value pair in either aligned or stacked form, adds separator lines between records, and returns the finished list of terminal lines with hyperlink information preserved.

Call relations: The main table renderer calls this after deciding that record layout is better than grid layout. Inside, it delegates each field to render_aligned_field or render_stacked_field, and uses widest_line_width when it must create a separator without a known terminal width.

Call graph: calls 3 internal fn (render_aligned_field, render_stacked_field, new); called by 1 (render_table_lines); 5 external calls (from, styled, new, iter, iter).

fn render_aligned_field(
    out: &mut Vec<HyperlinkLine>,
    header: &TableCell,
    value: &TableCell,
    label_width: usize,
    available_width: Option<usize>,
    label_style: Style,
)

Purpose: Draws one field with the label on the left and the value starting in a consistent column. This is the easier-to-scan layout used when there is enough horizontal room.

Data flow: It receives the output list, a header cell, a value cell, the shared label width, optional available width, and the label style. It computes where the value should begin, wraps the value to the remaining width, adds the styled label only on the first wrapped line, indents later wrapped lines to line up with the value, and appends the resulting lines to the output.

Call relations: render_records calls this for each header/value pair when the terminal is wide enough for aligned fields. It relies on wrap_cell to split the value into readable lines, then hands each prefixed line to push_prefixed_value_line so hyperlink positions stay correct after indentation.

Call graph: calls 3 internal fn (plain_text, push_prefixed_value_line, wrap_cell); called by 1 (render_records); 3 external calls (raw, styled, new).

fn render_stacked_field(
    out: &mut Vec<HyperlinkLine>,
    header: &TableCell,
    value: &TableCell,
    available_width: Option<usize>,
    label_style: Style,
)

Purpose: Draws one field with the label above the value. This is used when the terminal is too narrow to fit labels and values side by side without making the value unreadable.

Data flow: It receives the output list, a header cell, a value cell, optional available width, and the label style. It wraps the label to the available label width and writes it with a small leading space. Then it wraps the value to the remaining width and writes it underneath with a slightly larger indent. The finished lines are appended to the output.

Call relations: render_records calls this when aligned fields would not leave enough room for values. It uses the general word-wrapping helper for labels, wrap_cell for values, and push_prefixed_value_line to attach indentation while preserving hyperlink positions.

Call graph: calls 7 internal fn (plain_text, push_prefixed_value_line, wrap_cell, push_owned_lines, new, new, word_wrap_line); called by 1 (render_records); 4 external calls (from, styled, new, vec!).

fn push_prefixed_value_line(
    out: &mut Vec<HyperlinkLine>,
    mut prefix: Vec<Span<'static>>,
    mut value_line: HyperlinkLine,
)

Purpose: Adds indentation or label text in front of a value line while keeping any terminal hyperlinks attached to the right characters. This is important because adding spaces before linked text changes its column positions.

Data flow: It receives the output list, a prefix made of text spans, and a value line that may contain hyperlinks. It measures the display width of the prefix, joins the prefix and value spans into one line, shifts every hyperlink range to the right by that prefix width, and pushes the corrected line into the output.

Call relations: Both render_aligned_field and render_stacked_field call this whenever they add a wrapped value line. It is the small but important bridge between visual formatting and accurate clickable link metadata.

Call graph: calls 1 internal fn (new); called by 2 (render_aligned_field, render_stacked_field); 1 external calls (from).

fn wrap_cell(cell: &TableCell, width: usize) -> Vec<HyperlinkLine>

Purpose: Wraps the visual contents of a table cell to a target width while preserving hyperlink information. It turns one possibly long cell into one or more terminal lines that fit the chosen width.

Data flow: It receives a table cell and a width. For each source line in the cell, it word-wraps the visible text, converts the wrapped lines into owned terminal lines, and remaps hyperlinks from the original line onto the new wrapped pieces. It returns the wrapped lines, or a blank line if the cell has no visible content.

Call relations: The record renderer uses this before drawing values in both aligned and stacked layouts. expansive_cells_are_starved also uses it as a measuring tool to estimate how tall a cell would become at a given column width.

Call graph: calls 4 internal fn (new, remap_wrapped_line, new, word_wrap_line); called by 2 (render_aligned_field, render_stacked_field); 3 external calls (default, new, vec!).

fn cell_width(cell: &TableCell) -> usize

Purpose: Finds the widest visible line inside a table cell. This is used when there is no fixed terminal width and the renderer needs a natural width for wrapping or spacing.

Data flow: It receives a table cell, measures the display width of every span in every line, and takes the largest total line width. It returns that maximum width, or zero for an empty cell.

Call relations: render_aligned_field and render_stacked_field use this when no available terminal width was supplied. It gives those functions a sensible fallback width based on the cell’s actual content.

fn widest_line_width(lines: &[HyperlinkLine]) -> usize

Purpose: Finds the widest rendered output line so separator lines can match the content width when no terminal width is known.

Data flow: It receives already-rendered lines, measures the visible width of each line by adding up its spans, and returns the largest width found. If there are no lines, it returns zero.

Call relations: render_records uses this when inserting separator lines between record blocks and no explicit available width was provided. It lets the separator grow to the width of the content already produced.

Call graph: 1 external calls (iter).

fn syntax_set() -> &'static SyntaxSet

Purpose: Returns the shared database of language grammars used to recognize code. It builds that database only once because it is large and reused everywhere highlighting happens.

Data flow: It takes no input. The first time it is called, it loads the bundled two_face syntax set; later calls reuse the same stored value. It returns a reference to that shared syntax database.

Call relations: Language lookup and the core highlighter call this when they need grammar information. It is the common source of truth for both finding a language and parsing each highlighted line.

Call graph: called by 2 (find_syntax, highlight_to_line_spans_with_theme).

fn set_theme_override(
    name: Option<String>,
    codex_home: Option<PathBuf>,
) -> Option<String>

Purpose: Records the user’s configured syntax theme and custom-theme folder after configuration is finalized. It also updates the active theme immediately if the theme system has already started.

Data flow: It receives an optional theme name and optional Codex home path. It validates the name, stores the settings in write-once global slots, may resolve and apply the theme, and returns an optional warning message for the user.

Call relations: The app startup flow calls this from run_ratatui_app. It delegates checking to validate_theme_name, theme resolution to resolve_theme_with_override, and live application to set_syntax_theme.

Call graph: calls 3 internal fn (resolve_theme_with_override, set_syntax_theme, validate_theme_name); called by 1 (run_ratatui_app); 1 external calls (debug!).

fn validate_theme_name(name: Option<&str>, codex_home: Option<&Path>) -> Option<String>

Purpose: Checks whether a requested theme name is usable. It gives a clear warning when a user typed an unknown built-in theme or pointed to a missing or broken custom theme file.

Data flow: It receives an optional theme name and optional home folder. If there is no name or the name matches a bundled theme, it returns no warning; otherwise it looks for and tries to parse a matching .tmTheme file, returning a warning string if that fails.

Call relations: set_theme_override calls this before saving the configuration. Tests call it directly to make sure users get useful messages for missing or invalid custom themes.

Call graph: calls 3 internal fn (custom_theme_path, load_custom_theme, parse_theme_name); called by 3 (set_theme_override, validate_theme_name_warns_for_missing_custom, validate_theme_name_warns_when_custom_file_is_invalid); 1 external calls (format!).

fn parse_theme_name(name: &str) -> Option<EmbeddedThemeName>

Purpose: Translates the public kebab-case theme name, such as catppuccin-mocha, into the internal two_face theme identifier. This lets config files use readable names.

Data flow: It receives a string. If the string is one of the known bundled theme names, it returns the matching internal enum value; otherwise it returns nothing.

Call relations: Theme validation, theme resolution, and configured-theme reporting all use this as the first step before trying custom theme files.

Call graph: called by 4 (configured_theme_name, resolve_theme_by_name, resolve_theme_with_override, validate_theme_name).

fn custom_theme_path(name: &str, codex_home: &Path) -> PathBuf

Purpose: Builds the expected file path for a custom theme. It standardizes the rule that custom themes live under themes inside the Codex home folder.

Data flow: It receives a theme name and a home directory path. It returns a path like {home}/themes/{name}.tmTheme.

Call relations: Custom-theme loading and validation both call this so they look in the same place and format user-facing warnings consistently.

Call graph: called by 2 (load_custom_theme, validate_theme_name); 2 external calls (join, format!).

fn load_custom_theme(name: &str, codex_home: &Path) -> Option<Theme>

Purpose: Attempts to read and parse a user-provided .tmTheme file. This is what lets users bring their own syntax color themes.

Data flow: It receives a theme name and home directory. It builds the expected path, asks syntect to load the theme file, and returns the parsed theme if successful or nothing if the file is missing or invalid.

Call relations: Theme validation, theme resolution, and configured-theme lookup use this after bundled theme lookup fails. A test also calls it directly with a temporary theme file.

Call graph: calls 1 internal fn (custom_theme_path); called by 5 (configured_theme_name, resolve_theme_by_name, resolve_theme_with_override, load_custom_theme_from_tmtheme_file, validate_theme_name); 1 external calls (get_theme).

fn adaptive_default_theme_selection() -> (EmbeddedThemeName, &'static str)

Purpose: Chooses a default theme that fits the terminal background. Light terminals get a light theme; other terminals get a dark theme.

Data flow: It reads the terminal’s default background color if known. It checks whether that color is light and returns both the internal theme identifier and the public theme name for the selected default.

Call relations: The helper functions for default embedded theme and default theme name both call this so the visual default and the displayed name stay in sync.

Call graph: calls 2 internal fn (is_light, default_bg); called by 2 (adaptive_default_embedded_theme_name, adaptive_default_theme_name).

fn adaptive_default_embedded_theme_name() -> EmbeddedThemeName

Purpose: Returns the internal identifier for the automatically chosen default theme. It is used when the program needs the actual theme object.

Data flow: It takes no input. It calls the adaptive default selector and returns only the internal theme value.

Call relations: Theme resolution calls this when there is no valid user override and it needs to load the fallback bundled theme.

Call graph: calls 1 internal fn (adaptive_default_theme_selection); called by 1 (resolve_theme_with_override).

fn adaptive_default_theme_name() -> &'static str

Purpose: Returns the readable name of the automatically chosen default theme. This is useful for display and selection state.

Data flow: It takes no input. It calls the adaptive default selector and returns only the kebab-case name string.

Call relations: Theme-picker setup and configured-theme reporting use this when no valid configured theme is available.

Call graph: calls 1 internal fn (adaptive_default_theme_selection); called by 2 (restore_runtime_theme_from_config, configured_theme_name).

fn resolve_theme_with_override(name: Option<&str>, codex_home: Option<&Path>) -> Theme

Purpose: Builds the active theme from a user override if possible, otherwise from the adaptive default. It is the main decision point for theme selection.

Data flow: It receives an optional theme name and optional custom-theme home. It first tries bundled themes, then custom files, and finally falls back to the adaptive default theme. It returns a concrete theme object.

Call relations: Startup default construction and set_theme_override call this. It uses parse_theme_name, load_custom_theme, and adaptive_default_embedded_theme_name to work through the choices.

Call graph: calls 3 internal fn (adaptive_default_embedded_theme_name, load_custom_theme, parse_theme_name); called by 2 (build_default_theme, set_theme_override); 2 external calls (debug!, extra).

fn build_default_theme() -> Theme

Purpose: Creates the theme used when the theme lock is first initialized. It respects the saved startup override if one was recorded.

Data flow: It reads the stored theme override and stored Codex home path from global slots. It passes those values to resolve_theme_with_override and returns the resulting theme.

Call relations: theme_lock calls this lazily when the active theme has not yet been created.

Call graph: calls 1 internal fn (resolve_theme_with_override).

fn theme_lock() -> &'static RwLock<Theme>

Purpose: Returns the shared lock around the active syntax theme. The lock lets the app read the current theme while still allowing safe runtime theme swaps.

Data flow: It takes no input. On first use it creates a read-write lock containing build_default_theme; later it returns the same lock.

Call relations: Theme readers, theme writers, and highlighters all pass through this helper so they coordinate through the same active theme.

Call graph: called by 3 (current_syntax_theme, highlight_to_line_spans, set_syntax_theme).

fn set_syntax_theme(theme: Theme)

Purpose: Replaces the active syntax theme while the app is running. This supports live preview and theme changes without restarting.

Data flow: It receives a theme object. It takes the write side of the theme lock, recovering even if another thread previously panicked while holding it, and stores the new theme.

Call relations: Theme preview, restore-from-config flow, and set_theme_override call this when they need the visible highlighting colors to change immediately.

Call graph: calls 1 internal fn (theme_lock); called by 3 (restore_runtime_theme_from_config, handle_event, set_theme_override).

fn current_syntax_theme() -> Theme

Purpose: Returns a copy of the active syntax theme. Callers use this when they need to inspect or save the current theme without changing it.

Data flow: It takes no input. It reads the theme lock, clones the theme, and returns that clone; if the lock is poisoned, it still recovers the contained theme.

Call relations: Diff-color extraction, foreground-style lookup, and theme-picker setup call this to work from the current live theme.

Call graph: calls 1 internal fn (theme_lock); called by 3 (diff_scope_background_rgbs, foreground_style_for_scopes, build_theme_picker_params).

fn diff_scope_background_rgbs() -> DiffScopeBackgroundRgbs

Purpose: Finds insert and delete background colors from the current syntax theme for diff rendering. This lets diffs match the selected theme when the theme provides those colors.

Data flow: It reads the current theme, asks the pure helper to inspect it, and returns optional raw RGB colors for inserted and deleted text.

Call relations: The diff rendering setup calls this through resolve_diff_backgrounds. It hands the actual extraction work to diff_scope_background_rgbs_for_theme.

Call graph: calls 2 internal fn (current_syntax_theme, diff_scope_background_rgbs_for_theme); called by 1 (resolve_diff_backgrounds).

fn diff_scope_background_rgbs_for_theme(theme: &Theme) -> DiffScopeBackgroundRgbs

Purpose: Extracts diff background colors from a specific theme. It prefers modern TextMate scope names and falls back to older diff scope names.

Data flow: It receives a theme. It creates a syntect highlighter, asks for backgrounds for inserted and deleted scopes, and returns a small struct holding the optional RGB values.

Call relations: The live-theme wrapper calls this in production, while tests call it with hand-built or loaded themes to verify the extraction rules.

Call graph: calls 1 internal fn (scope_background_rgb); called by 5 (diff_scope_background_rgbs, bundled_theme_can_provide_diff_scope_backgrounds, custom_tmtheme_diff_scope_backgrounds_are_resolved, diff_scope_backgrounds_prefer_markup_scope_then_diff_fallback, diff_scope_backgrounds_return_none_when_no_background_scope_matches); 1 external calls (new).

fn scope_background_rgb(highlighter: &Highlighter<'_>, scope_name: &str) -> Option<(u8, u8, u8)>

Purpose: Looks up the background color for one TextMate scope name. A scope is a label like markup.inserted that themes can attach colors to.

Data flow: It receives a highlighter and a scope name string. It parses the scope, asks the theme what background that scope would use, and returns the color as red, green, and blue bytes if present.

Call relations: diff_scope_background_rgbs_for_theme calls this repeatedly while searching for inserted and deleted diff colors.

Call graph: called by 1 (diff_scope_background_rgbs_for_theme); 2 external calls (style_mod_for_stack, new).

fn foreground_style_for_scopes(scope_names: &[&str]) -> Option<Style>

Purpose: Finds the first foreground text style supplied by the active theme for a list of scope names. Other UI pieces use this to borrow theme colors for labels and tables.

Data flow: It receives a list of scope-name strings. It copies the current theme, searches the scopes in order, and returns a ratatui Style if a foreground color is found.

Call relations: UI styling code such as label_style, numeric_style, theme_activity_style, and render_table_lines call this to make non-code interface elements match the syntax theme.

Call graph: calls 2 internal fn (current_syntax_theme, foreground_style_for_scopes_with_theme); called by 4 (label_style, numeric_style, theme_activity_style, render_table_lines).

fn foreground_style_for_scopes_with_theme(theme: &Theme, scope_names: &[&str]) -> Option<Style>

Purpose: Searches a given theme for a foreground color on one of several scopes. It is the testable core behind foreground_style_for_scopes.

Data flow: It receives a theme and ordered scope names. It checks each scope, converts the first found syntect color into a terminal color, and returns a Style with that foreground.

Call relations: The live wrapper calls this with the current theme. Tests call it with small artificial themes to confirm first-match behavior.

Call graph: called by 3 (foreground_style_for_scopes, foreground_style_for_scopes_reads_matching_theme_scope, foreground_style_for_scopes_uses_first_scope_with_foreground); 1 external calls (new).

fn configured_theme_name() -> String

Purpose: Reports the theme name that should count as configured: a valid user choice if available, otherwise the adaptive default. It ignores temporary live-preview swaps.

Data flow: It reads the stored override and Codex home. If the override is a bundled theme or valid custom theme, it returns that name; otherwise it returns the adaptive default name.

Call relations: The theme picker calls this to decide which item should appear selected. Tests use it indirectly to ensure unavailable settings fall back cleanly.

Call graph: calls 3 internal fn (adaptive_default_theme_name, load_custom_theme, parse_theme_name); called by 2 (build_theme_picker_params, unavailable_configured_theme_falls_back_to_configured_or_default_selection).

fn resolve_theme_by_name(name: &str, codex_home: Option<&Path>) -> Option<Theme>

Purpose: Turns a theme name into a concrete theme object for previews and restores. It returns nothing when neither a bundled nor custom theme exists.

Data flow: It receives a name and optional custom-theme home. It tries the bundled theme table first, then tries a custom .tmTheme file, and returns the loaded theme if either works.

Call relations: Theme-picker events and restore-from-config use this to apply selected names. Tests also use it to fetch built-in and custom themes for color checks.

Call graph: calls 2 internal fn (load_custom_theme, parse_theme_name); called by 6 (restore_runtime_theme_from_config, handle_event, ansi_family_themes_use_terminal_palette_colors_not_rgb, bundled_theme_can_provide_diff_scope_backgrounds, custom_tmtheme_diff_scope_backgrounds_are_resolved, unique_foreground_colors_for_theme); 1 external calls (extra).

fn list_available_themes(codex_home: Option<&Path>) -> Vec<ThemeEntry>

Purpose: Builds the list of themes the picker can show. It combines bundled themes with valid custom .tmTheme files found on disk.

Data flow: It receives an optional home directory. It starts with all built-in names, scans {home}/themes for parseable .tmTheme files, skips invalid files and duplicate names, sorts the result, and returns entries marked as built-in or custom.

Call relations: Theme-picker setup calls this to populate choices. Tests call it to check that invalid files are hidden and ordering is stable.

Call graph: called by 3 (list_available_themes_excludes_invalid_custom_files, list_available_themes_returns_stable_sorted_order, build_theme_picker_params); 2 external calls (get_theme, read_dir).

fn ansi_palette_color(index: u8) -> RtColor

Purpose: Converts a terminal palette index into ratatui’s color type. Low indexes become named terminal colors so terminals can apply their usual behavior.

Data flow: It receives a number from 0 to 255. Values 0 through 7 become named colors like red or blue, while larger values become indexed terminal colors.

Call relations: convert_syntect_color calls this when syntect marks a color as an ANSI palette color instead of a true RGB color.

Call graph: called by 1 (convert_syntect_color); 1 external calls (Indexed).

fn convert_syntect_color(color: SyntectColor) -> Option<RtColor>

Purpose: Converts syntect’s color format into ratatui’s terminal color format. It understands a special alpha-byte convention used by ANSI-style themes.

Data flow: It receives a syntect color with red, green, blue, and alpha bytes. Some alpha values mean “use palette index” or “use terminal default”; otherwise it returns an RGB terminal color.

Call relations: convert_style uses this while translating each highlighted text span from syntect style data into terminal style data.

Call graph: calls 1 internal fn (ansi_palette_color); called by 1 (convert_style); 1 external calls (Rgb).

fn convert_style(syn_style: SyntectStyle) -> Style

Purpose: Turns a syntect style into a ratatui style that the terminal UI can render. It keeps foreground color and bold text, but intentionally avoids backgrounds, italics, and underlines.

Data flow: It receives a syntect style. It converts the foreground color, adds bold when requested, skips distracting or poorly supported attributes, and returns a ratatui Style.

Call relations: The core highlighter calls this for every colored piece of code. Multiple tests call it directly to lock down color and text-decoration behavior.

Call graph: calls 1 internal fn (convert_syntect_color); called by 7 (highlight_to_line_spans_with_theme, convert_style_suppresses_underline, style_conversion_correctness, style_conversion_unexpected_alpha_falls_back_to_rgb, style_conversion_uses_ansi_named_color_when_alpha_is_zero_low_index, style_conversion_uses_indexed_color_when_alpha_is_zero_high_index, style_conversion_uses_terminal_default_when_alpha_is_one); 1 external calls (default).

fn find_syntax(lang: &str) -> Option<&'static SyntaxReference>

Purpose: Finds the language grammar for a language name or file extension. It also patches common aliases that the bundled grammar set does not recognize directly.

Data flow: It receives a language string such as rust, rs, or python3. It normalizes a few aliases, tries token lookup, exact name lookup, case-insensitive name lookup, and extension lookup, then returns the matching grammar if found.

Call relations: highlight_to_line_spans_with_theme calls this before trying to highlight code. If it returns nothing, callers fall back to plain text.

Call graph: calls 1 internal fn (syntax_set); called by 1 (highlight_to_line_spans_with_theme).

fn exceeds_highlight_limits(total_bytes: usize, total_lines: usize) -> bool

Purpose: Checks whether a body of text is too large to highlight safely. This protects the UI from slow or memory-heavy highlighting work.

Data flow: It receives total byte count and line count. It compares them to fixed limits and returns true when either limit is exceeded.

Call relations: Diff rendering calls this before doing repeated per-line highlighting, so it can skip syntax highlighting for oversized changes.

Call graph: called by 1 (render_change).

fn highlight_to_line_spans_with_theme(
    code: &str,
    lang: &str,
    theme: &Theme,
) -> Option<Vec<Vec<Span<'static>>>>

Purpose: This is the core highlighter. It parses code for a specific language and theme and returns styled spans grouped by source line.

Data flow: It receives source code, a language name, and a theme. It rejects empty or oversized input, finds a grammar, highlights each line, strips line-ending characters, converts styles, and returns per-line spans; failure returns nothing.

Call relations: The global-theme wrapper calls this in production. Tests and color-palette checks also call it directly with specific themes.

Call graph: calls 3 internal fn (convert_style, find_syntax, syntax_set); called by 3 (highlight_to_line_spans, ansi_family_themes_use_terminal_palette_colors_not_rgb, unique_foreground_colors_for_theme); 6 external calls (new, from, raw, styled, new, new).

fn highlight_to_line_spans(code: &str, lang: &str) -> Option<Vec<Vec<Span<'static>>>>

Purpose: Highlights code using the currently active global theme. It is the normal internal path used by public rendering helpers.

Data flow: It receives code and a language name. It reads the active theme lock, passes the code and theme to highlight_to_line_spans_with_theme, and returns the optional styled spans.

Call relations: highlight_code_to_lines and highlight_code_to_styled_spans call this before deciding whether to render styled text or fall back.

Call graph: calls 2 internal fn (highlight_to_line_spans_with_theme, theme_lock); called by 2 (highlight_code_to_lines, highlight_code_to_styled_spans).

fn highlight_code_to_lines(code: &str, lang: &str) -> Vec<Line<'static>>

Purpose: Returns terminal-renderable lines for code, styled when possible and plain when not. Callers can safely render its output without doing their own fallback logic.

Data flow: It receives code and a language name. If highlighting succeeds, it turns each group of styled spans into a Line; otherwise it splits the original text into plain Lines, preserving empty input as one empty line.

Call relations: Markdown code blocks, bash highlighting, and many tests use this as the friendly public API for code-to-terminal-lines conversion.

Call graph: calls 1 internal fn (highlight_to_line_spans); called by 9 (end_codeblock, highlight_bash_to_lines, fallback_trailing_newline_no_phantom_line, highlight_crlf_strips_carriage_return, highlight_empty_string, highlight_markdown_preserves_content, highlight_multiline_python, highlight_rust_has_keyword_style, highlight_unknown_lang_falls_back); 2 external calls (from, new).

fn highlight_bash_to_lines(script: &str) -> Vec<Line<'static>>

Purpose: Convenience wrapper for highlighting shell scripts as Bash. It keeps older call sites simple and compatible.

Data flow: It receives a script string. It passes that script to highlight_code_to_lines with the language fixed to bash and returns the resulting Lines.

Call relations: Command display and transcript rendering call this when showing shell commands. It delegates all real work to highlight_code_to_lines.

Call graph: calls 1 internal fn (highlight_code_to_lines); called by 4 (build_header, command_display_lines, transcript_lines, highlight_bash_preserves_content).

fn highlight_code_to_styled_spans(
    code: &str,
    lang: &str,
) -> Option<Vec<Vec<Span<'static>>>>

Purpose: Returns styled spans for code so another renderer, especially the diff renderer, can combine syntax colors with its own layout. It signals failure with None.

Data flow: It receives code and a language name. It tries the active-theme highlighting path and returns per-line styled spans, or None for unknown languages and oversized input.

Call relations: Diff preview and snapshot tests call this when they need raw spans rather than complete terminal Lines.

Call graph: calls 1 internal fn (highlight_to_line_spans); called by 8 (ui_snapshot_syntax_highlighted_insert_wraps, ui_snapshot_syntax_highlighted_insert_wraps_text, update_diff_preserves_multiline_highlight_state_within_hunk, highlight_code_to_styled_spans_returns_some_for_known, highlight_large_input_falls_back, highlight_many_lines_falls_back, highlight_many_lines_no_trailing_newline_falls_back, render_preview).

fn write_minimal_tmtheme(path: &Path)

Purpose: Creates a tiny valid custom theme file for tests. It avoids needing real user theme files in the repository.

Data flow: It receives a path. It writes a minimal XML .tmTheme document to that path and panics if writing fails.

Call relations: Custom-theme loading and listing tests call this while building temporary theme directories.

Call graph: 1 external calls (write).

fn write_tmtheme_with_diff_backgrounds(
        path: &Path,
        inserted_scope: &str,
        inserted_background: &str,
        deleted_scope: &str,
        deleted_background: &str,
    )

Purpose: Creates a test theme file with specific diff insert and delete background colors. This lets tests check custom diff-color extraction.

Data flow: It receives a path, two scope names, and two color strings. It formats those values into a .tmTheme XML file and writes it to disk.

Call relations: The custom diff-background test calls this before resolving the custom theme by name.

Call graph: 2 external calls (format!, write).

fn reconstructed(lines: &[Line<'static>]) -> String

Purpose: Rebuilds plain text from rendered Lines so tests can confirm highlighting did not change the content. Coloring should decorate text, not rewrite it.

Data flow: It receives a slice of Lines. It concatenates each line’s span text and joins lines with newline characters, returning the reconstructed string.

Call relations: Several highlighting tests use this to compare rendered output back to the original source text.

Call graph: 1 external calls (iter).

fn unique_foreground_colors_for_theme(theme_name: &str) -> Vec<String>

Purpose: Collects the distinct foreground colors produced by one built-in theme on a Rust snippet. It supports tests that verify ANSI-family themes use terminal palette colors.

Data flow: It receives a theme name. It resolves that theme, highlights a small Rust program with it, extracts foreground colors from spans, sorts and deduplicates them, and returns debug strings.

Call relations: The ANSI palette snapshot test calls this for each ANSI-family theme.

Call graph: calls 2 internal fn (highlight_to_line_spans_with_theme, resolve_theme_by_name).

fn theme_item(scope: &str, background: Option<(u8, u8, u8)>) -> ThemeItem

Purpose: Builds a synthetic theme rule with an optional background color for tests. It is a small factory for theme-scope fixtures.

Data flow: It receives a scope name and optional RGB background. It parses the scope and returns a ThemeItem whose style contains that background if provided.

Call relations: Diff-background tests use this to assemble small in-memory themes without loading files.

Call graph: 2 external calls (from_str, default).

fn theme_item_with_foreground(scope: &str, foreground: (u8, u8, u8)) -> ThemeItem

Purpose: Builds a synthetic theme rule with a foreground color for tests. It makes foreground-style lookup tests easy to read.

Data flow: It receives a scope name and RGB foreground. It parses the scope and returns a ThemeItem whose style sets that foreground.

Call relations: Foreground-style tests use this when creating in-memory themes.

Call graph: 2 external calls (from_str, default).

fn assert_rgb(color: Option<RtColor>, expected: (u8, u8, u8))

Purpose: Checks that an optional ratatui color is the expected RGB value. It gives tests a compact way to validate converted colors.

Data flow: It receives an optional color and expected RGB tuple. It panics if the color is missing or not RGB, otherwise compares the channel values.

Call relations: Foreground-style tests call this after asking the theme lookup helper for a Style.

Call graph: 2 external calls (assert_eq!, panic!).

fn highlight_rust_has_keyword_style()

Purpose: Verifies that Rust highlighting both preserves the source text and applies a non-default style to the fn keyword.

Data flow: It highlights a small Rust snippet, reconstructs the text, finds the span containing fn, and asserts that span has color or bold styling.

Call relations: This test exercises the public highlight_code_to_lines path and indirectly covers language lookup, theme use, and style conversion.

Call graph: calls 1 internal fn (highlight_code_to_lines); 2 external calls (assert!, assert_eq!).

fn highlight_unknown_lang_falls_back()

Purpose: Confirms that unknown languages render as plain text instead of failing. This is important because users may type arbitrary code fence labels.

Data flow: It highlights text with a fake language name, reconstructs the output, and checks that every span has the default style.

Call relations: This test drives highlight_code_to_lines through the fallback branch caused by find_syntax returning no grammar.

Call graph: calls 1 internal fn (highlight_code_to_lines); 1 external calls (assert_eq!).

fn fallback_trailing_newline_no_phantom_line()

Purpose: Ensures the plain-text fallback does not create an extra empty line just because the input ends with a newline.

Data flow: It sends text ending in \n through an unknown language fallback and asserts that only the real content line is returned.

Call relations: This guards the fallback behavior inside highlight_code_to_lines, especially for Markdown code blocks.

Call graph: calls 1 internal fn (highlight_code_to_lines); 1 external calls (assert_eq!).

fn highlight_empty_string()

Purpose: Checks that empty code still produces one empty renderable line. This prevents callers from having to special-case empty blocks.

Data flow: It highlights an empty string as Rust and asserts the output has one line whose reconstructed content is empty.

Call relations: This test covers the empty-input fallback in highlight_code_to_lines.

Call graph: calls 1 internal fn (highlight_code_to_lines); 1 external calls (assert_eq!).

fn highlight_bash_preserves_content()

Purpose: Verifies that Bash command highlighting keeps the command text exactly the same.

Data flow: It passes a shell command through highlight_bash_to_lines, reconstructs the result, and compares it to the original script.

Call relations: This checks the bash wrapper while also exercising the general code highlighting path.

Call graph: calls 1 internal fn (highlight_bash_to_lines); 1 external calls (assert_eq!).

fn highlight_crlf_strips_carriage_return()

Purpose: Ensures Windows-style line endings do not leave stray carriage-return characters in rendered spans.

Data flow: It highlights Rust code containing \r\n line endings and asserts no output span contains \r.

Call relations: This test targets the line-ending cleanup inside highlight_to_line_spans_with_theme through the public line API.

Call graph: calls 1 internal fn (highlight_code_to_lines); 1 external calls (assert!).

fn style_conversion_correctness()

Purpose: Checks the main rules for converting syntect styles into terminal styles. It confirms foreground and bold survive while background and italic do not.

Data flow: It builds a syntect style with RGB foreground, background, bold, and italic. It converts it and asserts the expected ratatui style fields.

Call relations: This directly tests convert_style, which the highlighter uses for every styled span.

Call graph: calls 1 internal fn (convert_style); 2 external calls (assert!, assert_eq!).

fn convert_style_suppresses_underline()

Purpose: Confirms underlines from themes are deliberately ignored. Some themes underline common code names, which looks noisy in terminals.

Data flow: It builds a syntect style that requests underline, converts it, and asserts the terminal style does not include underline.

Call relations: This protects a specific design choice in convert_style.

Call graph: calls 1 internal fn (convert_style); 1 external calls (assert!).

fn style_conversion_uses_ansi_named_color_when_alpha_is_zero_low_index()

Purpose: Checks that an ANSI-theme color with a low palette index becomes a named terminal color. This preserves terminal-native color behavior.

Data flow: It creates a syntect foreground whose alpha byte marks it as an ANSI index and whose red byte is the index for green, then asserts conversion returns Green.

Call relations: This tests convert_style and the special color decoding behind convert_syntect_color.

Call graph: calls 1 internal fn (convert_style); 2 external calls (empty, assert_eq!).

fn style_conversion_uses_indexed_color_when_alpha_is_zero_high_index()

Purpose: Checks that higher ANSI palette indexes become indexed terminal colors. This supports 256-color themes.

Data flow: It builds a style with the ANSI-index marker and a high palette number, converts it, and asserts the result is an indexed color.

Call relations: This protects the high-index branch used by convert_syntect_color through convert_style.

Call graph: calls 1 internal fn (convert_style); 2 external calls (empty, assert!).

fn style_conversion_uses_terminal_default_when_alpha_is_one()

Purpose: Confirms the special marker for “use the terminal default color” results in no explicit foreground. That lets the terminal decide the color.

Data flow: It creates a style with alpha set to the terminal-default marker, converts it, and checks the foreground is absent.

Call relations: This directly verifies convert_syntect_color behavior as surfaced through convert_style.

Call graph: calls 1 internal fn (convert_style); 2 external calls (empty, assert_eq!).

fn style_conversion_unexpected_alpha_falls_back_to_rgb()

Purpose: Checks that unusual alpha values are treated as ordinary RGB colors. This keeps non-ANSI themes working even if they contain semi-transparent-looking values.

Data flow: It builds a style with an unexpected alpha byte and RGB channels, converts it, and asserts the RGB channels are preserved.

Call relations: This guards the compatibility branch in convert_syntect_color through convert_style.

Call graph: calls 1 internal fn (convert_style); 2 external calls (empty, assert!).

fn ansi_palette_color_maps_ansi_white_to_gray()

Purpose: Verifies the terminal color index for ANSI white maps to ratatui’s Gray variant. This matches ratatui’s naming for the standard palette.

Data flow: It calls ansi_palette_color with index 7 and compares the result to Gray.

Call relations: This directly tests one important case in the palette mapping used by convert_syntect_color.

Call graph: 1 external calls (assert_eq!).

fn ansi_family_themes_use_terminal_palette_colors_not_rgb()

Purpose: Ensures ANSI-family built-in themes produce terminal palette colors rather than forced RGB colors. This lets those themes respect the user’s terminal palette.

Data flow: For each ANSI-family theme, it resolves the theme, highlights Rust code, scans span foregrounds, rejects RGB colors, and confirms at least one explicit non-default color appears.

Call relations: This test exercises resolve_theme_by_name and highlight_to_line_spans_with_theme together.

Call graph: calls 2 internal fn (highlight_to_line_spans_with_theme, resolve_theme_by_name); 2 external calls (assert!, panic!).

fn ansi_family_foreground_palette_snapshot()

Purpose: Records the set of foreground colors produced by ANSI-family themes. The snapshot helps catch accidental changes in palette behavior.

Data flow: It collects unique foreground color strings for each ANSI-family theme, builds a readable text report, and compares it to an approved snapshot.

Call relations: It relies on tests::unique_foreground_colors_for_theme, which in turn uses theme resolution and core highlighting.

Call graph: 4 external calls (new, assert_snapshot!, format!, unique_foreground_colors_for_theme).

fn highlight_multiline_python()

Purpose: Verifies that multiline Python highlighting preserves text and line count.

Data flow: It highlights a three-line Python snippet, reconstructs the text, and asserts both content and number of lines match expectations.

Call relations: This covers the public highlight_code_to_lines path for a common non-Rust language.

Call graph: calls 1 internal fn (highlight_code_to_lines); 1 external calls (assert_eq!).

fn highlight_code_to_styled_spans_returns_none_for_unknown()

Purpose: Checks that the span-oriented API clearly signals an unknown language with None.

Data flow: It asks for styled spans using a fake language name and asserts the result is absent.

Call relations: This guards the fallback signal used by diff rendering through highlight_code_to_styled_spans.

Call graph: 1 external calls (assert!).

fn highlight_code_to_styled_spans_returns_some_for_known()

Purpose: Checks that the span-oriented API returns styled data for a known language.

Data flow: It highlights a small Rust snippet, asserts the result exists, and checks it contains at least one line of spans.

Call relations: This tests highlight_code_to_styled_spans on the success path used by diff previews.

Call graph: calls 1 internal fn (highlight_code_to_styled_spans); 1 external calls (assert!).

fn highlight_markdown_preserves_content()

Purpose: Ensures Markdown syntax highlighting does not alter nested fence-like content. This matters for displaying Markdown code blocks accurately.

Data flow: It highlights a Markdown snippet containing backticks and shell text, reconstructs the output, and compares it exactly to the input.

Call relations: This uses highlight_code_to_lines and tests::reconstructed to protect content preservation.

Call graph: calls 1 internal fn (highlight_code_to_lines); 2 external calls (assert_eq!, reconstructed).

fn highlight_large_input_falls_back()

Purpose: Confirms code larger than the byte limit is not highlighted. This prevents expensive work on huge inputs.

Data flow: It creates a string just over the maximum byte limit, asks for styled spans, and asserts the result is None.

Call relations: This targets the guardrail inside highlight_to_line_spans_with_theme through highlight_code_to_styled_spans.

Call graph: calls 1 internal fn (highlight_code_to_styled_spans); 1 external calls (assert!).

fn highlight_many_lines_falls_back()

Purpose: Confirms input with too many lines is not highlighted. This protects the UI from slow parsing of very long snippets.

Data flow: It creates more than the allowed number of lines, requests styled spans, and asserts highlighting is skipped.

Call relations: This checks the line-count guardrail in the highlighting path used by diff rendering.

Call graph: calls 1 internal fn (highlight_code_to_styled_spans); 1 external calls (assert!).

fn highlight_many_lines_no_trailing_newline_falls_back()

Purpose: Ensures the line limit counts actual lines, not just newline characters. A final line without a newline must still count.

Data flow: It builds text with one too many lines but no trailing newline, verifies the line count, and asserts highlighting returns None.

Call relations: This protects the precise line-count logic inside highlight_to_line_spans_with_theme.

Call graph: calls 1 internal fn (highlight_code_to_styled_spans); 2 external calls (assert!, assert_eq!).

fn find_syntax_resolves_languages_and_aliases()

Purpose: Verifies the syntax lookup can recognize many common languages, file extensions, and patched aliases.

Data flow: It loops through language names, extensions, and aliases, checking that each can be resolved to a syntax grammar.

Call relations: This directly protects find_syntax, the gatekeeper for whether highlighting can happen.

Call graph: 1 external calls (assert!).

fn diff_scope_backgrounds_prefer_markup_scope_then_diff_fallback()

Purpose: Checks that diff background extraction prefers markup.* scopes and falls back to diff.* scopes when needed.

Data flow: It creates an in-memory theme with an inserted markup background and a deleted diff background, extracts colors, and compares them to expected RGB values.

Call relations: This tests diff_scope_background_rgbs_for_theme with artificial theme rules.

Call graph: calls 1 internal fn (diff_scope_background_rgbs_for_theme); 4 external calls (default, default, assert_eq!, vec!).

fn diff_scope_backgrounds_return_none_when_no_background_scope_matches()

Purpose: Confirms diff color extraction returns no colors when the theme has no relevant insert/delete backgrounds.

Data flow: It creates a theme with an unrelated background scope, extracts diff backgrounds, and asserts both inserted and deleted values are absent.

Call relations: This guards the fallback behavior of diff_scope_background_rgbs_for_theme.

Call graph: calls 1 internal fn (diff_scope_background_rgbs_for_theme); 4 external calls (default, default, assert_eq!, vec!).

fn foreground_style_for_scopes_reads_matching_theme_scope()

Purpose: Verifies foreground-style lookup can read a color from a matching scope.

Data flow: It creates a theme with a keyword foreground, asks for the keyword style, and asserts the RGB color matches.

Call relations: This directly tests foreground_style_for_scopes_with_theme with a simple in-memory theme.

Call graph: calls 1 internal fn (foreground_style_for_scopes_with_theme); 4 external calls (default, default, assert_rgb, vec!).

fn foreground_style_for_scopes_uses_first_scope_with_foreground()

Purpose: Checks that foreground-style lookup searches scopes in order and returns the first one that has a foreground.

Data flow: It creates a theme with only a string foreground, asks for keyword then string, and asserts the returned style uses the string color.

Call relations: This protects the ordered search behavior in foreground_style_for_scopes_with_theme.

Call graph: calls 1 internal fn (foreground_style_for_scopes_with_theme); 4 external calls (default, default, assert_rgb, vec!).

fn bundled_theme_can_provide_diff_scope_backgrounds()

Purpose: Ensures at least one bundled theme exposes diff insert and delete background colors. This confirms the extraction path works on real bundled data.

Data flow: It resolves the built-in GitHub theme, extracts diff backgrounds from it, and asserts both inserted and deleted colors exist.

Call relations: This combines resolve_theme_by_name with diff_scope_background_rgbs_for_theme.

Call graph: calls 2 internal fn (diff_scope_background_rgbs_for_theme, resolve_theme_by_name); 1 external calls (assert!).

fn custom_tmtheme_diff_scope_backgrounds_are_resolved()

Purpose: Verifies custom .tmTheme files can provide diff background colors. This supports themed diff rendering for user-installed themes.

Data flow: It creates a temporary themes folder, writes a custom theme with diff colors, resolves it by name, extracts backgrounds, and compares RGB values.

Call relations: This uses the custom theme writer, resolve_theme_by_name, and diff_scope_background_rgbs_for_theme together.

Call graph: calls 2 internal fn (diff_scope_background_rgbs_for_theme, resolve_theme_by_name); 4 external calls (assert_eq!, create_dir, tempdir, write_tmtheme_with_diff_backgrounds).

fn parse_theme_name_covers_all_variants()

Purpose: Checks that every expected public built-in theme name maps to the correct internal theme identifier.

Data flow: It iterates through known name-to-identifier pairs and asserts parse_theme_name returns the expected value for each.

Call relations: This directly protects the built-in mapping used by validation and theme resolution.

Call graph: 1 external calls (assert_eq!).

fn parse_theme_name_returns_none_for_unknown()

Purpose: Checks that unknown or empty theme names are not mistaken for bundled themes.

Data flow: It calls parse_theme_name with invalid strings and asserts the result is None.

Call relations: This guards the failure branch that lets custom-theme lookup or fallback logic run.

Call graph: 1 external calls (assert_eq!).

fn load_custom_theme_from_tmtheme_file()

Purpose: Verifies a valid custom theme file can be loaded from the expected folder.

Data flow: It creates a temporary home, writes a minimal .tmTheme under themes, calls load_custom_theme, and asserts a theme is returned.

Call relations: This directly tests the custom-theme loading path used by validation and theme resolution.

Call graph: calls 1 internal fn (load_custom_theme); 4 external calls (assert!, create_dir, tempdir, write_minimal_tmtheme).

fn load_custom_theme_returns_none_for_missing()

Purpose: Checks that missing custom theme files simply return None rather than crashing.

Data flow: It creates an empty temporary directory, asks for a nonexistent theme, and asserts no theme is returned.

Call relations: This protects the missing-file behavior of load_custom_theme.

Call graph: 2 external calls (assert!, tempdir).

fn validate_theme_name_none_for_bundled()

Purpose: Ensures bundled theme names never produce configuration warnings.

Data flow: It validates known bundled theme names with and without a real home directory and asserts no warning is returned.

Call relations: This tests validate_theme_name on the built-in success path.

Call graph: 1 external calls (assert!).

fn validate_theme_name_none_when_no_override()

Purpose: Ensures no warning appears when the user did not configure a theme override.

Data flow: It calls validate_theme_name with no name and asserts the result is None.

Call relations: This protects the normal default-theme startup path.

Call graph: 1 external calls (assert!).

fn validate_theme_name_warns_for_missing_custom()

Purpose: Checks that a missing custom theme produces a helpful warning mentioning the requested name.

Data flow: It validates a custom-looking name in an empty temporary home, unwraps the warning, and checks the message includes the theme name.

Call relations: This directly exercises validate_theme_name’s missing-custom-file branch.

Call graph: calls 1 internal fn (validate_theme_name); 2 external calls (assert!, tempdir).

fn validate_theme_name_none_when_custom_file_is_valid()

Purpose: Verifies valid custom theme files do not create startup warnings.

Data flow: It writes a minimal valid .tmTheme into a temporary themes folder, validates that theme name, and asserts no warning is returned.

Call relations: This covers validate_theme_name’s custom-theme success path.

Call graph: 4 external calls (assert!, create_dir, tempdir, write_minimal_tmtheme).

fn validate_theme_name_warns_when_custom_file_is_invalid()

Purpose: Checks that a present but unparsable custom theme file produces an actionable warning.

Data flow: It writes invalid text to a .tmTheme file, validates that name, and asserts the warning says the file could not be loaded.

Call relations: This tests the invalid-custom-file branch in validate_theme_name.

Call graph: calls 1 internal fn (validate_theme_name); 4 external calls (assert!, create_dir, write, tempdir).

fn list_available_themes_excludes_invalid_custom_files()

Purpose: Ensures the theme picker does not list broken custom theme files. Users should only see themes that can actually load.

Data flow: It creates one valid and one invalid custom theme file, lists available themes, and asserts only the valid custom theme appears.

Call relations: This directly tests list_available_themes with temporary filesystem data.

Call graph: calls 1 internal fn (list_available_themes); 5 external calls (assert!, create_dir, write, tempdir, write_minimal_tmtheme).

fn list_available_themes_returns_stable_sorted_order()

Purpose: Checks that theme listing order is stable and case-insensitive. Stable ordering keeps the picker predictable across platforms.

Data flow: It creates several custom themes with mixed names, lists all themes, independently sorts the observed entries the same way, and compares both lists.

Call relations: This protects the sorting behavior in list_available_themes.

Call graph: calls 1 internal fn (list_available_themes); 4 external calls (assert_eq!, create_dir, tempdir, write_minimal_tmtheme).

fn parse_theme_name_is_exhaustive()

Purpose: Ensures the local theme-name mapping stays in sync with the themes bundled by two_face. If the dependency adds themes, this test forces an update.

Data flow: It asks two_face for all embedded theme variants, checks the expected count, maps all local kebab-case names, and asserts every embedded variant is covered.

Call relations: This is a safety net for parse_theme_name and the built-in theme list.

Call graph: 3 external calls (theme_names, assert!, assert_eq!).

fn default() -> Self

Purpose: Creates the standard visual styles used for rendered Markdown, such as bold headings, cyan code, underlined links, and green blockquotes.

Data flow: It takes no input, builds a MarkdownStyles value from default ratatui styles plus colors and text effects, and returns that style set.

Call relations: A new Writer calls this during setup so every later Markdown event can ask for the right style when drawing text.

Call graph: called by 1 (new); 1 external calls (new).

fn new(prefix: Vec<Span<'static>>, marker: Option<Vec<Span<'static>>>, is_list: bool) -> Self

Purpose: Builds one indentation rule for nested structures like lists, blockquotes, and code blocks.

Data flow: It receives prefix spans, an optional list marker, and a flag saying whether this context is a list, then stores them together for later line prefixing.

Call relations: List items, blockquotes, and code blocks call this when they begin so later output lines know what leading text, such as > or - , should be added.

Call graph: called by 3 (start_blockquote, start_codeblock, start_item).

fn ensure_line(&mut self)

Purpose: Makes sure a table cell has at least one line ready before content is appended.

Data flow: It reads the cell's current line list; if it is empty, it adds a blank HyperlinkLine. It returns nothing but changes the cell.

Call relations: Cell-writing helpers call this before adding styled spans or annotated hyperlink content, so table cell content always has a place to go.

Call graph: calls 1 internal fn (new); called by 2 (push_annotated, push_span); 1 external calls (default).

fn push_span(&mut self, span: Span<'static>)

Purpose: Adds one styled piece of visible text to the current line of a table cell.

Data flow: It receives a span, creates the first line if needed, and appends the span to the cell's last line.

Call relations: Markdown text, inline code, and tests use this simple path when no hyperlink remapping is needed.

Call graph: calls 1 internal fn (ensure_line).

fn push_annotated(&mut self, mut appended: HyperlinkLine)

Purpose: Adds a line fragment that may contain terminal hyperlinks into a table cell while keeping link positions correct.

Data flow: It receives a HyperlinkLine, measures the existing cell line width, appends the new spans, shifts every incoming hyperlink range by that width, and stores them in the cell.

Call relations: The table text renderer uses this when text in a table cell contains web URLs or explicit Markdown links.

Call graph: calls 1 internal fn (ensure_line).

fn hard_break(&mut self)

Purpose: Starts a new logical line inside a table cell, matching a Markdown hard break or multi-line HTML/text content.

Data flow: It appends a blank HyperlinkLine to the cell. Later content will be written on that new line.

Call relations: Markdown break handling and table-cell HTML/text helpers call this so multi-line table cells keep their intended breaks.

Call graph: calls 1 internal fn (new); 1 external calls (default).

fn plain_text(&self) -> String

Purpose: Creates an unstyled text-only version of a table cell for measuring and classification.

Data flow: It walks all lines and spans in the cell, joins line breaks as spaces, and returns one plain string.

Call relations: Table layout code uses this text when deciding column widths, identifying long-token columns, and detecting spillover rows.

Call graph: called by 2 (render_aligned_field, render_stacked_field); 2 external calls (new, write!).

fn new(alignments: Vec<Alignment>) -> Self

Purpose: Starts an empty table accumulator when the Markdown parser enters a table.

Data flow: It receives the table's column alignments and returns a state object with no header, no rows, and no active cell yet.

Call relations: The writer creates this at table start; later table-head, row, and cell events fill it until table end renders it.

Call graph: called by 1 (start_table); 1 external calls (new).

fn render_markdown_text(input: &str) -> Text<'static>

Purpose: Renders Markdown into terminal text when no specific terminal width is available.

Data flow: It receives a Markdown string, passes it to the width-aware renderer with no width, and returns ratatui Text.

Call relations: Tests and callers that do not know the viewport use this convenience function; it delegates all real work to the width-aware path.

Call graph: calls 1 internal fn (render_markdown_text_with_width); called by 72 (vt100_deep_nested_mixed_list_third_level_marker_is_colored, crlf_code_block_no_extra_blank_lines, fenced_code_info_string_with_metadata_highlights, blockquote_heading_inherits_heading_style, blockquote_in_ordered_list_on_next_line, blockquote_in_unordered_list_on_next_line, blockquote_inside_nested_list, blockquote_list_then_nested_blockquote, blockquote_multiple_with_break, blockquote_nested_two_levels (+15 more)).

fn render_markdown_text_with_width(input: &str, width: Option<usize>) -> Text<'static>

Purpose: Renders Markdown while respecting a known terminal width, using the process's current directory for local file-link display.

Data flow: It receives Markdown and an optional width, reads the current working directory if available, then returns styled Text from the fuller renderer.

Call relations: This is the common public-width entry used by tests and rendering helpers; it passes control to the version that accepts an explicit working directory.

Call graph: calls 1 internal fn (render_markdown_text_with_width_and_cwd); called by 20 (render_markdown_text, does_not_split_long_url_like_token_without_scheme, does_not_wrap_code_blocks, wraps_blockquotes, wraps_blockquotes_inside_lists, wraps_list_items_containing_blockquotes, wraps_list_items_preserving_indent, wraps_nested_lists, wraps_ordered_lists, wraps_plain_text_when_width_provided (+10 more)); 1 external calls (current_dir).

fn render_markdown_text_with_width_and_cwd(
    input: &str,
    width: Option<usize>,
    cwd: Option<&Path>,
) -> Text<'static>

Purpose: Renders Markdown to visible terminal text using both a width and a chosen working directory.

Data flow: It receives Markdown, optional width, and optional cwd, renders hyperlink-aware lines, removes or exposes visible lines as needed, and wraps them into Text.

Call relations: Higher-level transcript rendering calls this when it knows the session directory, so local file links are displayed consistently.

Call graph: calls 2 internal fn (render_markdown_lines_with_width_and_cwd, visible_lines); called by 8 (append_markdown, append_markdown_agent, render_markdown_text_with_width, consecutive_unordered_list_local_file_links_do_not_detach_paths, render_markdown_text_for_cwd, table_wraps_file_paths_before_collapsing_narrative_columns_snapshot, unordered_list_local_file_link_soft_break_before_colon_stays_inline, unordered_list_local_file_link_stays_inline_with_following_text); 1 external calls (from).

fn render_markdown_lines_with_width_and_cwd(
    input: &str,
    width: Option<usize>,
    cwd: Option<&Path>,
) -> Vec<HyperlinkLine>

Purpose: Renders Markdown into hyperlink-aware lines before they are converted to plain visible ratatui text.

Data flow: It enables Markdown options for tables and strikethrough, creates the parser, feeds events into a Writer, runs it, and returns the writer's finished lines.

Call relations: This is the main bridge from parsed Markdown events into the Writer; callers that need hyperlink metadata use it directly.

Call graph: calls 2 internal fn (new, new); called by 10 (render_markdown_agent_with_links_and_cwd, render_markdown_text_with_width_and_cwd, annotates_explicit_web_link_label_and_visible_destination, does_not_annotate_code_or_non_web_markdown_links, key_value_table_keeps_web_annotations, pipe_table_fallback_keeps_web_annotations, wrapped_table_url_fragments_keep_complete_web_destination, bare_url_with_tilde_keeps_complete_hyperlink, merged_text_events_preserve_entity_decoding, table_url_with_tilde_keeps_complete_hyperlink); 2 external calls (empty, new_ext).

fn should_render_link_destination(dest_url: &str) -> bool

Purpose: Decides whether a link should show its destination text after the label.

Data flow: It receives a destination string and returns false for local path-like links, true for normal non-local links.

Call relations: When a link starts, Writer::push_link uses this to choose between web-link display rules and local-file display rules.

Call graph: calls 1 internal fn (is_local_path_like_link); called by 1 (push_link).

fn new(input: &'a str, iter: I, wrap_width: Option<usize>, cwd: Option<&Path>) -> Self

Purpose: Creates the stateful Markdown event writer that will build terminal lines.

Data flow: It receives the original Markdown, an event iterator, optional wrap width, and optional cwd, then initializes style stacks, indentation stacks, table state, link state, and output buffers.

Call relations: The line-rendering entry function constructs one writer and then calls Writer::run to consume the Markdown events.

Call graph: calls 1 internal fn (default); called by 1 (render_markdown_lines_with_width_and_cwd); 3 external calls (new, default, new).

fn run(&mut self)

Purpose: Consumes every Markdown event and finishes any partially built line.

Data flow: It repeatedly pulls events from the parser iterator, sends each to handle_event, then flushes the last current line into output.

Call relations: This is the writer's main loop, called once after construction by the Markdown-line rendering function.

Call graph: calls 2 internal fn (flush_current_line, handle_event); 1 external calls (next).

fn handle_event(&mut self, event: Event<'a>, range: Range<usize>)

Purpose: Dispatches one parsed Markdown event to the specific logic for that event type.

Data flow: It receives an event and source range, resolves any pending local-link soft-break behavior, then calls the matching start, end, text, code, break, rule, or HTML handler.

Call relations: The run loop calls this for every parser event; it is the switchboard that routes Markdown structure to the writer's specialized methods.

Call graph: calls 11 internal fn (code, end_tag, flush_current_line, hard_break, html, prepare_for_event, push_blank_line, push_line, soft_break, start_tag (+1 more)); called by 1 (run); 1 external calls (from).

fn prepare_for_event(&mut self, event: &Event<'a>)

Purpose: Deals with a delayed soft break after a local file link before the next event is processed.

Data flow: It checks whether a soft break was held back. If the next text starts with a colon, it keeps the content inline; otherwise it inserts a blank line.

Call relations: Called at the start of event handling so local file-link list items do not split awkwardly before descriptions like : changed file.

Call graph: calls 1 internal fn (push_line); called by 1 (handle_event); 2 external calls (default, matches!).

fn start_tag(&mut self, tag: Tag<'a>, range: Range<usize>)

Purpose: Handles the beginning of a Markdown structure such as a paragraph, heading, list item, link, code block, or table.

Data flow: It receives a start tag and its source range, then updates writer state or starts collecting content for the corresponding structure.

Call relations: The event dispatcher calls this for Event::Start; it hands work to structure-specific methods like start_table or start_heading.

Call graph: calls 12 internal fn (push_inline_style, push_link, start_blockquote, start_codeblock, start_heading, start_item, start_list, start_paragraph, start_table, start_table_cell (+2 more)); called by 1 (handle_event); 1 external calls (from).

fn end_tag(&mut self, tag: TagEnd)

Purpose: Handles the end of a Markdown structure and closes any state opened by start_tag.

Data flow: It receives an end tag, flushes or updates the relevant state, pops styles or indentation, and may render accumulated structures such as tables or code blocks.

Call relations: The event dispatcher calls this for Event::End; it pairs with start_tag to keep nesting and output boundaries correct.

Call graph: calls 12 internal fn (end_blockquote, end_codeblock, end_heading, end_list, end_paragraph, end_table, end_table_cell, end_table_head, end_table_row, flush_current_line (+2 more)); called by 1 (handle_event).

fn start_paragraph(&mut self)

Purpose: Begins a normal paragraph outside tables.

Data flow: It checks whether rendering is currently inside a table cell. If not, it inserts needed spacing, starts a new line, and marks paragraph mode active.

Call relations: Called when a paragraph tag starts; it prepares the current output line before text events arrive.

Call graph: calls 3 internal fn (in_table_cell, push_blank_line, push_line); called by 1 (start_tag); 1 external calls (default).

fn end_paragraph(&mut self)

Purpose: Marks the end of a paragraph so following block content gets separated correctly.

Data flow: It ignores table cells, otherwise records that a newline is needed and clears paragraph/list-marker state.

Call relations: Called from end-tag handling after paragraph content has been written.

Call graph: calls 1 internal fn (in_table_cell); called by 1 (end_tag).

fn start_heading(&mut self, level: HeadingLevel)

Purpose: Begins a Markdown heading with visible # marker text and heading style.

Data flow: It receives the heading level, chooses the matching style, starts a line containing the right number of # characters, and pushes that style for heading text.

Call relations: Start-tag handling calls this for headings; later text events use the pushed style until end_heading pops it.

Call graph: calls 3 internal fn (in_table_cell, push_inline_style, push_line); called by 1 (start_tag); 4 external calls (default, from, format!, vec!).

fn end_heading(&mut self)

Purpose: Closes heading mode after the heading text has been written.

Data flow: It ignores table cells, otherwise marks that a new line is needed and removes the heading style from the inline style stack.

Call relations: End-tag handling calls this to balance start_heading.

Call graph: calls 2 internal fn (in_table_cell, pop_inline_style); called by 1 (end_tag).

fn start_blockquote(&mut self)

Purpose: Starts a blockquote by adding a > prefix context.

Data flow: It inserts spacing if needed, then pushes an indentation context whose prefix is > .

Call relations: Called from start-tag handling; later line creation reads the indentation stack so quoted lines receive the prefix and quote style.

Call graph: calls 3 internal fn (new, in_table_cell, push_blank_line); called by 1 (start_tag); 1 external calls (vec!).

fn end_blockquote(&mut self)

Purpose: Ends the current blockquote.

Data flow: It ignores table cells, otherwise removes the blockquote indentation context and marks that a newline is needed.

Call relations: End-tag handling calls this to balance start_blockquote.

Call graph: calls 1 internal fn (in_table_cell); called by 1 (end_tag).

fn text(&mut self, text: CowStr<'a>)

Purpose: Writes normal Markdown text to the current output location.

Data flow: It receives parsed text, skips it if it is the label of a local file link, sends it to a table cell if inside one, buffers it for syntax-highlighted code blocks when needed, or writes styled/wrapped text lines otherwise.

Call relations: The event dispatcher calls this for text events; it feeds either table-cell helpers or regular line helpers depending on current state.

Call graph: calls 5 internal fn (in_table_cell, push_line, push_text_spans, push_text_to_table_cell, suppressing_local_link_label); called by 1 (handle_event); 2 external calls (lines, default).

fn code(&mut self, code: CowStr<'a>)

Purpose: Writes inline code text with the code style.

Data flow: It receives code content, suppresses local-link labels if needed, then either appends a styled span to the current table cell or to the current normal line.

Call relations: The event dispatcher calls this for inline code events; it uses the same table-vs-normal split as plain text.

Call graph: calls 5 internal fn (in_table_cell, push_line, push_span, push_span_to_table_cell, suppressing_local_link_label); called by 1 (handle_event); 3 external calls (into_string, default, from).

fn html(&mut self, html: CowStr<'a>, inline: bool)

Purpose: Writes Markdown HTML content as visible text rather than interpreting it as real terminal markup.

Data flow: It receives HTML text and a flag saying whether it is inline. It writes each line with the current style, adding hard breaks for block HTML when appropriate.

Call relations: The event dispatcher calls this for HTML events; table-cell HTML is routed through table-cell helpers so it remains inside the table.

Call graph: calls 6 internal fn (in_table_cell, push_line, push_span, push_span_to_table_cell, push_table_cell_hard_break, suppressing_local_link_label); called by 1 (handle_event); 3 external calls (lines, default, styled).

fn hard_break(&mut self)

Purpose: Implements a Markdown hard line break.

Data flow: It skips suppressed local-link labels, then either starts a new line inside the active table cell or starts a new output line.

Call relations: The event dispatcher calls this for hard-break events.

Call graph: calls 4 internal fn (in_table_cell, push_line, push_table_cell_hard_break, suppressing_local_link_label); called by 1 (handle_event); 1 external calls (default).

fn soft_break(&mut self)

Purpose: Implements a Markdown soft line break with special handling after local file links.

Data flow: It writes a space inside table cells, delays the break if it follows a local file-link target, or otherwise starts a new output line.

Call relations: The event dispatcher calls this for soft-break events; prepare_for_event later decides whether a delayed local-link break should become a real line break.

Call graph: calls 4 internal fn (in_table_cell, push_line, push_span_to_table_cell, suppressing_local_link_label); called by 1 (handle_event); 2 external calls (default, styled).

fn start_list(&mut self, index: Option<u64>)

Purpose: Starts an ordered or unordered list and records its numbering state.

Data flow: It receives an optional starting number, adds spacing if this is a top-level list after previous content, and pushes list counters and blank-line tracking state.

Call relations: Called when a list tag starts; list item rendering later reads and updates this state.

Call graph: calls 1 internal fn (push_line); called by 1 (start_tag); 1 external calls (default).

fn end_list(&mut self)

Purpose: Ends the current list.

Data flow: It removes the current list counter and blank-line flag, then marks that later block content should begin on a new line.

Call relations: End-tag handling calls this when the Markdown list closes.

Call graph: called by 1 (end_tag).

fn start_item(&mut self)

Purpose: Starts one list item and prepares its bullet or number marker.

Data flow: It handles any blank line needed between multi-line items, flushes current output, records where the item begins, computes the visible marker and indentation, and pushes an indentation context.

Call relations: Called from start-tag handling for list items; when the item ends, end-tag handling pops the context and may request blank spacing before the next item.

Call graph: calls 3 internal fn (new, flush_current_line, push_blank_line); called by 1 (start_tag); 2 external calls (new, vec!).

fn start_codeblock(&mut self, lang: Option<String>, indent: Option<Span<'static>>)

Purpose: Starts a fenced or indented code block and prepares either syntax highlighting or plain code output.

Data flow: It receives an optional language and optional indent span, flushes prior content, adds spacing, extracts a clean language token, clears the code buffer, and pushes code indentation.

Call relations: Start-tag handling calls this for code blocks; text events may be buffered until end_codeblock performs highlighting.

Call graph: calls 3 internal fn (new, flush_current_line, push_blank_line); called by 1 (start_tag); 1 external calls (vec!).

fn end_codeblock(&mut self)

Purpose: Finishes a code block and emits buffered highlighted code if a language was known.

Data flow: It takes the buffered code, asks the highlighter for styled lines, writes those spans, then clears code-block state and removes the code indentation context.

Call relations: End-tag handling calls this when the parser leaves a code block.

Call graph: calls 3 internal fn (push_line, push_span, highlight_code_to_lines); called by 1 (end_tag); 2 external calls (default, take).

fn start_table(&mut self, alignments: Vec<Alignment>)

Purpose: Begins collecting a Markdown table instead of immediately writing lines.

Data flow: It flushes current output, inserts spacing if needed, and creates a TableState with the table alignments.

Call relations: Start-tag handling calls this for table tags; later table row and cell events fill the state until end_table renders it.

Call graph: calls 3 internal fn (new, flush_current_line, push_blank_line); called by 1 (start_tag).

fn end_table(&mut self)

Purpose: Turns the collected table state into output lines.

Data flow: It takes the active TableState, asks render_table_lines to lay it out, then pushes prewrapped table lines and any extracted spillover prose into the transcript.

Call relations: End-tag handling calls this for table close; it is where accumulated table events become visible terminal output.

Call graph: calls 4 internal fn (flush_current_line, push_hyperlink_line, push_prewrapped_line, render_table_lines); called by 1 (end_tag).

fn start_table_head(&mut self)

Purpose: Marks that following table row events belong to the table header.

Data flow: It sets the table state to header mode and starts an empty current row.

Call relations: Called by start-tag handling inside a table before header cell events arrive.

Call graph: called by 1 (start_tag); 1 external calls (new).

fn end_table_head(&mut self)

Purpose: Stores the completed header row in the table state.

Data flow: It flushes any open current cell into the current row, moves the row into the header field, and leaves header mode.

Call relations: Called by end-tag handling after the header section of a table.

Call graph: called by 1 (end_tag).

fn start_table_row(&mut self, source_range: Range<usize>)

Purpose: Starts collecting one table row and notes whether the source text used boundary pipes.

Data flow: It receives the source range, checks the original Markdown for leading or trailing pipe characters, and creates an empty current row in the table state.

Call relations: Start-tag handling calls this for every table row; the pipe-syntax flag later helps detect parser spillover rows.

Call graph: calls 1 internal fn (has_table_row_boundary_pipe); called by 1 (start_tag); 1 external calls (new).

fn has_table_row_boundary_pipe(&self, source_range: Range<usize>) -> bool

Purpose: Checks whether a parsed table row looked like an explicit pipe table row in the source Markdown.

Data flow: It receives a source range, slices the original input, trims it, and returns whether it starts or ends with |.

Call relations: Used only when starting a table row, and its result is stored for later spillover detection.

Call graph: called by 1 (start_table_row).

fn end_table_row(&mut self)

Purpose: Stores the completed table row as either the header or a body row.

Data flow: It flushes any current cell into the current row, then moves that row into the header or body list, carrying the pipe-syntax flag for body rows.

Call relations: End-tag handling calls this at row close; render_table_lines later consumes the stored rows.

Call graph: called by 1 (end_tag).

fn start_table_cell(&mut self)

Purpose: Starts collecting styled content for one table cell.

Data flow: It creates an empty TableCell in the active table state.

Call relations: Start-tag handling calls this before text, code, link, or HTML events that belong inside the cell.

Call graph: called by 1 (start_tag); 1 external calls (default).

fn end_table_cell(&mut self)

Purpose: Finishes the current table cell and appends it to the current row.

Data flow: It takes the active cell, creates a row if needed, and pushes the cell into that row.

Call relations: End-tag handling calls this after all events for a table cell have arrived.

Call graph: called by 1 (end_tag).

fn in_table_cell(&self) -> bool

Purpose: Answers whether the writer is currently collecting content inside a table cell.

Data flow: It checks whether table state exists and has an active current cell, then returns a boolean.

Call relations: Many event handlers call this to decide whether to write to normal transcript lines or to the table accumulator.

Call graph: called by 12 (code, end_blockquote, end_heading, end_paragraph, hard_break, html, pop_link, soft_break, start_blockquote, start_heading (+2 more)).

fn push_span_to_table_cell(&mut self, span: Span<'static>)

Purpose: Adds a styled span directly to the active table cell.

Data flow: It receives a span, finds the active cell if one exists, and appends the span there.

Call relations: Inline code, HTML, link closing, and soft-break handling use this while inside table cells.

Call graph: called by 4 (code, html, pop_link, soft_break).

fn push_table_cell_hard_break(&mut self)

Purpose: Adds a hard line break inside the active table cell.

Data flow: It finds the active cell and asks it to start a new internal line.

Call relations: Hard-break, HTML, and multi-line text handling call this when cell content must split across lines.

Call graph: called by 3 (hard_break, html, push_text_to_table_cell).

fn push_text_to_table_cell(&mut self, text: &str)

Purpose: Writes plain text into the current table cell while preserving source line breaks.

Data flow: It receives text, gets the current inline style, splits text into lines, inserts table-cell hard breaks between them, and sends each line to the annotated table-cell writer.

Call relations: The main text handler calls this whenever text arrives while a table cell is active.

Call graph: calls 2 internal fn (push_table_cell_hard_break, push_text_spans_to_table_cell); called by 1 (text).

fn push_text_spans_to_table_cell(&mut self, text: &str, style: Style)

Purpose: Writes one line of text into a table cell, adding hyperlink annotations when appropriate.

Data flow: It receives text and style, turns it into a span, attaches an explicit web-link destination or detects bare web URLs unless links/code should suppress that, then appends the annotated content to the current cell.

Call relations: Used by table-cell text writing so links inside tables keep working after table wrapping.

Call graph: calls 2 internal fn (new, annotate_web_urls_in_line); called by 1 (push_text_to_table_cell); 4 external calls (default, from, styled, take).

fn render_table_lines(&self, mut table_state: TableState) -> RenderedTableLines

Purpose: Converts a completed table into readable terminal lines.

Data flow: It receives a TableState, separates accidental spillover prose, normalizes row widths, measures columns, computes available width, chooses aligned-table, key/value, or raw-pipe fallback layout, and returns table lines plus spillover lines.

Call relations: end_table calls this once the parser closes a table; it coordinates table measurement, rendering, and fallback helpers.

Call graph: calls 9 internal fn (available_record_width, available_table_width, compute_column_widths, render_table_pipe_fallback, render_table_row, render_records, should_render_records, foreground_style_for_scopes, table_separator_style); called by 1 (end_table); 7 external calls (collect_table_column_metrics, is_spillover_row, normalize_row, render_table_separator, default, new, with_capacity).

fn normalize_row(row: &mut Vec<TableCell>, column_count: usize)

Purpose: Forces a table row to have exactly the expected number of cells.

Data flow: It receives a mutable row and column count, truncates extra cells, and adds empty cells if the row is short.

Call relations: Table rendering calls this before measuring so every row can be indexed safely by column.

Call graph: 1 external calls (default).

fn available_table_width(&self, column_count: usize) -> Option<usize>

Purpose: Calculates how much horizontal space is available for table cell contents.

Data flow: It starts from the wrap width, subtracts current indentation, column gaps, and cell padding, and returns the remaining width if a wrap width exists.

Call relations: render_table_lines uses this budget when deciding whether an aligned table can fit.

Call graph: called by 1 (render_table_lines).

fn available_record_width(&self) -> Option<usize>

Purpose: Calculates the width available for key/value table fallback records.

Data flow: It starts from the wrap width, subtracts only the current line prefix, and returns the remaining content width.

Call relations: render_table_lines passes this to the key/value renderer when a normal grid would be unreadable.

Call graph: called by 1 (render_table_lines).

fn compute_column_widths(
        &self,
        header: &[TableCell],
        rows: &[Vec<TableCell>],
        alignments: &[Alignment],
        available_width: Option<usize>,
    ) -> Option<Vec<us

Purpose: Chooses table column widths that fit the terminal while trying to keep content readable.

Data flow: It receives header cells, body rows, alignments, and an optional width budget. It starts with natural widths, computes preferred floors, shrinks columns by priority, and returns widths or None if even minimum columns cannot fit.

Call relations: render_table_lines calls this before choosing between aligned rendering and fallback layouts.

Call graph: called by 1 (render_table_lines); 3 external calls (len, collect_table_column_metrics, next_column_to_shrink).

fn collect_table_column_metrics(
        header: &[TableCell],
        rows: &[Vec<TableCell>],
        column_count: usize,
    ) -> Vec<TableColumnMetrics>

Purpose: Measures each table column and classifies it as prose, token-heavy, or compact.

Data flow: It reads header and body cells, measures widest content and longest tokens, counts words, and returns per-column metrics used by width allocation.

Call relations: Both table rendering and column-width computation use these metrics to decide which columns should shrink first.

Call graph: 3 external calls (cell_display_width, longest_token_width, with_capacity).

fn preferred_column_floor(metrics: &TableColumnMetrics, min_column_width: usize) -> usize

Purpose: Chooses a soft minimum width for one table column before aggressive shrinking starts.

Data flow: It receives column metrics and a hard minimum, then returns a width based on column kind and token sizes, clamped to the column's actual maximum.

Call relations: compute_column_widths uses this floor so compact values and readable prose are not crushed too early.

fn next_column_to_shrink(
        widths: &[usize],
        floors: &[usize],
        metrics: &[TableColumnMetrics],
    ) -> Option<usize>

Purpose: Selects which table column should lose one character of width next.

Data flow: It receives current widths, floors, and metrics, filters to columns above their floor, and returns the best candidate based on shrink priority and slack.

Call relations: compute_column_widths repeatedly calls this until the table fits or no more useful shrinking is possible.

fn column_shrink_priority(kind: TableColumnKind) -> usize

Purpose: Ranks table column kinds for width reduction.

Data flow: It receives a column kind and returns a numeric priority: token-heavy columns shrink first, narrative next, compact last.

Call relations: Column-width helpers use this ranking to protect short status-like values and readable prose from being squeezed too soon.

fn render_table_separator(
        column_widths: &[usize],
        separator_char: char,
        style: Style,
    ) -> HyperlinkLine

Purpose: Builds a styled horizontal separator line for a rendered table.

Data flow: It receives column widths, a separator character, and a style, creates repeated segments with padding and gaps, and returns a hyperlink-free line.

Call relations: render_table_lines uses this between the header and body rows, and between body rows.

Call graph: calls 1 internal fn (new); 2 external calls (from, styled).

fn render_table_row(
        &self,
        row: &[TableCell],
        column_widths: &[usize],
        alignments: &[Alignment],
        row_style: Style,
    ) -> Vec<HyperlinkLine>

Purpose: Renders one table row into one or more prewrapped terminal lines.

Data flow: It wraps each cell to its column width, calculates row height, applies alignment and padding, shifts hyperlink ranges into their final columns, and returns the visible row lines.

Call relations: render_table_lines calls this for the header and each body row when aligned table rendering is chosen.

Call graph: calls 1 internal fn (new); called by 1 (render_table_lines); 7 external calls (default, from, line_display_width, raw, new, with_capacity, iter).

fn render_table_pipe_fallback(
        &self,
        header: &[TableCell],
        rows: &[Vec<TableCell>],
        alignments: &[Alignment],
    ) -> Vec<HyperlinkLine>

Purpose: Renders a table as raw Markdown-style pipe lines when no aligned layout fits and there are no body records to transpose.

Data flow: It receives header, rows, and alignments, converts them into | A | B | lines plus a delimiter line, and returns those lines for normal wrapping.

Call relations: render_table_lines uses this mainly for header-only tables where key/value records would not make sense.

Call graph: calls 1 internal fn (new); called by 1 (render_table_lines); 4 external calls (from, alignments_to_pipe_delimiter, row_to_pipe_line, new).

fn row_to_pipe_line(row: &[TableCell]) -> HyperlinkLine

Purpose: Converts one row of table cells into a pipe-delimited line while preserving hyperlinks.

Data flow: It walks each cell's visible text, escapes literal pipe characters as \|, tracks hyperlink destinations by display column, and writes spans into a new line.

Call relations: The pipe fallback renderer calls this for the header and body rows.

Call graph: calls 1 internal fn (new); 3 external calls (default, new, width).

fn alignments_to_pipe_delimiter(alignments: &[Alignment]) -> String

Purpose: Creates the Markdown delimiter row that represents table column alignment.

Data flow: It receives alignment values and returns a string such as |:---|---:|.

Call relations: The pipe fallback renderer uses this as the second row after the header.

Call graph: 1 external calls (new).

fn wrap_cell(&self, cell: &TableCell, width: usize) -> Vec<HyperlinkLine>

Purpose: Wraps one table cell to a column width without losing styles or hyperlinks.

Data flow: It receives a cell and width, wraps each internal cell line, converts wrapped lines to static terminal lines, remaps hyperlink ranges, and returns at least one line.

Call relations: render_table_row calls this for every cell before assembling padded table rows.

Call graph: calls 4 internal fn (new, remap_wrapped_line, new, word_wrap_line); 3 external calls (default, new, vec!).

fn is_spillover_row(row: &TableBodyRow, next_row: Option<&TableBodyRow>) -> bool

Purpose: Detects rows that are probably accidental table rows created by the Markdown parser's loose table parsing.

Data flow: It receives a body row and optional next row, checks whether only the first cell has content and whether it looks like prose or HTML spillover, and returns a boolean.

Call relations: render_table_lines uses this before layout so trailing paragraphs or HTML are shown after the table instead of inside it.

Call graph: 3 external calls (first_non_empty_only_text, looks_like_html_content, looks_like_html_label_line).

fn first_non_empty_only_text(row: &[TableCell]) -> Option<String>

Purpose: Finds text for rows where only the first table cell has content.

Data flow: It reads a row's cells, returns the first cell's plain text only if it is non-empty and every other cell is empty.

Call relations: Spillover detection calls this to decide whether a sparse row should be examined as possible escaped prose.

Call graph: 1 external calls (first).

fn looks_like_html_content(text: &str) -> bool

Purpose: Checks whether text appears to contain an HTML tag.

Data flow: It scans bytes for a <, optional / or !, an alphabetic tag name, and a later >, returning true if that pattern appears.

Call relations: Spillover detection uses this to move HTML-like parser artifacts out of tables.

fn looks_like_html_label_line(text: &str) -> bool

Purpose: Checks whether a line looks like a label introducing HTML content.

Data flow: It trims the text, requires a trailing colon, then looks for the word html before that colon.

Call relations: Spillover detection uses this for trailing lines such as HTML block:.

fn spans_display_width(spans: &[Span<'_>]) -> usize

Purpose: Measures the visible terminal width of a list of spans.

Data flow: It receives spans, sums the Unicode display width of each span's content, and returns the total.

Call relations: Line, table, and prefix width calculations use this helper whenever visual column counts matter.

Call graph: 1 external calls (iter).

fn line_display_width(line: &Line<'_>) -> usize

Purpose: Measures the visible width of one terminal line.

Data flow: It receives a line, forwards its spans to spans_display_width, and returns the result.

Call relations: Table row rendering uses this when padding and aligning cell lines.

Call graph: 1 external calls (spans_display_width).

fn cell_display_width(cell: &TableCell) -> usize

Purpose: Measures the widest visible line inside a table cell.

Data flow: It reads all lines in a cell, measures each line, and returns the maximum width or zero for an empty cell.

Call relations: Column metric collection uses this to find each column's natural width.

fn longest_token_width(text: &str) -> usize

Purpose: Finds the display width of the longest whitespace-separated token in text.

Data flow: It splits text by whitespace, measures each token, and returns the maximum width or zero.

Call relations: Column metric collection uses this to identify columns dominated by long paths, URLs, or hashes.

fn push_inline_style(&mut self, style: Style)

Purpose: Adds a new inline style while preserving any style already active.

Data flow: It receives a style, merges it with the current top style, and pushes the merged style onto the stack.

Call relations: Heading and emphasis/strong/strikethrough start handling call this so nested styles combine correctly.

Call graph: called by 2 (start_heading, start_tag).

fn pop_inline_style(&mut self)

Purpose: Removes the most recently pushed inline style.

Data flow: It pops the style stack and returns nothing.

Call relations: Heading and emphasis/strong/strikethrough end handling call this to restore the previous text style.

Call graph: called by 2 (end_heading, end_tag).

fn push_link(&mut self, dest_url: String)

Purpose: Starts tracking a Markdown link and decides how it should be displayed.

Data flow: It receives the destination string, decides whether to show the destination, prepares special local-file display text if needed, and stores a LinkState.

Call relations: Start-tag handling calls this for links; later text may be suppressed for local links, and pop_link finishes the visible output.

Call graph: calls 3 internal fn (is_local_path_like_link, render_local_link_target, should_render_link_destination); called by 1 (start_tag).

fn pop_link(&mut self)

Purpose: Finishes rendering a Markdown link.

Data flow: It takes the active link state. For web links it appends a styled destination suffix and hyperlink annotation; for local file links it writes the normalized target path instead of the label.

Call relations: End-tag handling calls this at link close; it writes either to the current table cell or the normal line depending on context.

Call graph: calls 7 internal fn (in_table_cell, push_annotated, push_line, push_span, push_span_to_table_cell, new, web_destination); called by 1 (end_tag); 2 external calls (default, styled).

fn suppressing_local_link_label(&self) -> bool

Purpose: Tells whether current link label text should be hidden because a local file target will be shown instead.

Data flow: It checks the active link state for prepared local-target display text and returns true if present.

Call relations: Text, code, HTML, and break handlers call this so arbitrary Markdown labels do not appear for local file links.

Call graph: called by 5 (code, hard_break, html, soft_break, text).

fn flush_current_line(&mut self)

Purpose: Moves the current in-progress line into final output, wrapping it if needed.

Data flow: It takes the current line, applies indentation, wraps non-code lines to the configured width, remaps hyperlinks after wrapping or prefixing, pushes completed lines, and clears current-line state.

Call relations: Many operations call this before starting a new block or preformatted line, and run calls it at the end.

Call graph: calls 4 internal fn (push_output_line, remap_wrapped_line, new, adaptive_wrap_line); called by 10 (end_table, end_tag, handle_event, push_blank_line, push_line, push_prewrapped_line, run, start_codeblock, start_item, start_table); 1 external calls (from_iter).

fn is_blockquote_active(&self) -> bool

Purpose: Checks whether any active indentation context represents a blockquote.

Data flow: It scans the indentation stack for a prefix containing > and returns a boolean.

Call relations: Line-pushing methods call this to apply blockquote styling to normal and prewrapped lines.

Call graph: called by 2 (push_line, push_prewrapped_line).

fn push_prewrapped_line(&mut self, mut line: HyperlinkLine, pending_marker_line: bool)

Purpose: Adds a line that has already been laid out and must not be word-wrapped again.

Data flow: It flushes current content, applies blockquote style if active, prepends the right prefix or list marker, shifts hyperlinks, and pushes the final line.

Call relations: end_table uses this for aligned or key/value table output because wrapping those lines again would break the layout.

Call graph: calls 5 internal fn (flush_current_line, is_blockquote_active, prefix_spans, push_output_line, style); called by 1 (end_table); 1 external calls (from).

fn push_line(&mut self, line: Line<'static>)

Purpose: Starts a new current line with the correct indentation and style context.

Data flow: It flushes any existing line, calculates initial and subsequent prefixes, records current style and code-block status, and stores the new line as in-progress.

Call relations: Most text-producing handlers call this whenever they need a fresh line.

Call graph: calls 4 internal fn (flush_current_line, is_blockquote_active, prefix_spans, new); called by 16 (code, end_codeblock, handle_event, hard_break, html, pop_link, prepare_for_event, push_annotated, push_blank_line, push_hyperlink_line (+6 more)).

fn push_hyperlink_line(&mut self, line: HyperlinkLine)

Purpose: Starts a new current line from an already hyperlink-aware line.

Data flow: It separates the line's spans and hyperlinks, pushes the spans as a line, then restores the hyperlink metadata onto the current line.

Call relations: end_table uses this for fallback and spillover lines that should still go through normal flushing.

Call graph: calls 1 internal fn (push_line); called by 1 (end_table).

fn push_span(&mut self, span: Span<'static>)

Purpose: Appends one styled span to the current line, creating a line if necessary.

Data flow: It receives a span and either pushes it onto the current line or starts a new line containing that span.

Call relations: Inline code, HTML, link finishing, and highlighted code output call this for simple span insertion.

Call graph: calls 1 internal fn (push_line); called by 4 (code, end_codeblock, html, pop_link); 2 external calls (from, vec!).

fn push_annotated(&mut self, mut appended: HyperlinkLine)

Purpose: Appends hyperlink-aware content to the current line while preserving link columns.

Data flow: It receives a HyperlinkLine, creates a current line if needed, appends its spans, shifts hyperlink ranges by the existing line width, and stores those links.

Call relations: Plain text URL annotation and web-link destination rendering use this to keep terminal hyperlinks accurate.

Call graph: calls 1 internal fn (push_line); called by 2 (pop_link, push_text_spans); 1 external calls (default).

fn push_text_spans(&mut self, text: &str, style: Style)

Purpose: Writes styled text to normal output and attaches web-link annotations when appropriate.

Data flow: It receives text and style, creates a span, either uses the active explicit web-link destination, suppresses auto-linking inside links/code, or detects bare web URLs, then appends the annotated content.

Call relations: The main text handler calls this for non-table text.

Call graph: calls 3 internal fn (push_annotated, new, annotate_web_urls_in_line); called by 1 (text); 3 external calls (default, from, styled).

fn push_blank_line(&mut self)

Purpose: Adds a blank line while respecting list indentation rules.

Data flow: It flushes current content, then either pushes a truly empty output line for list-only contexts or creates and flushes a prefixed blank line for other contexts.

Call relations: Block starts and horizontal rules call this when visual separation is needed.

Call graph: calls 4 internal fn (flush_current_line, push_line, push_output_line, new); called by 6 (handle_event, start_blockquote, start_codeblock, start_item, start_paragraph, start_table); 1 external calls (default).

fn push_output_line(&mut self, line: HyperlinkLine)

Purpose: Appends one completed hyperlink-aware line to the writer's final output.

Data flow: It receives a finished line and pushes it into the output vector.

Call relations: Only lower-level flushing and prewrapped-line helpers call this, making it the final sink for rendered lines.

Call graph: called by 3 (flush_current_line, push_blank_line, push_prewrapped_line).

fn prefix_spans(&self, pending_marker_line: bool) -> Vec<Span<'static>>

Purpose: Builds the visible indentation and list marker prefix for the next line.

Data flow: It receives whether a list marker is pending, walks the indentation stack, chooses marker or continuation prefixes, and returns spans to place before the line content.

Call relations: Line pushing and prewrapped table output call this so nested lists and blockquotes line up correctly.

Call graph: called by 2 (push_line, push_prewrapped_line); 1 external calls (new).

fn is_local_path_like_link(dest_url: &str) -> bool

Purpose: Identifies link destinations that look like local filesystem paths rather than ordinary web links.

Data flow: It receives a destination string and checks for forms such as file://, absolute Unix paths, ~/, relative paths, UNC paths, and Windows drive paths.

Call relations: Link setup and link-destination policy use this to choose local-file rendering behavior.

Call graph: called by 2 (push_link, should_render_link_destination); 1 external calls (matches!).

fn render_local_link_target(dest_url: &str, cwd: Option<&Path>) -> Option<String>

Purpose: Turns a local link destination into the exact path text shown in the transcript.

Data flow: It parses the destination into path and optional location suffix, displays the path relative to cwd when appropriate, appends the suffix, and returns the final string.

Call relations: Writer::push_link calls this when a link looks local so pop_link can render the real target instead of the Markdown label.

Call graph: calls 2 internal fn (display_local_link_path, parse_local_link_target); called by 1 (push_link).

fn parse_local_link_target(dest_url: &str) -> Option<(String, Option<String>)>

Purpose: Splits a local-link destination into normalized path text and an optional line/column suffix.

Data flow: It accepts file URLs and plain path-like strings, decodes URL escapes, recognizes #L... and trailing :line[:col] suffixes, expands home-relative paths, and returns the parsed pieces.

Call relations: Local-link rendering calls this before deciding how much of the path to display.

Call graph: calls 4 internal fn (expand_local_link_path, extract_colon_location_suffix, file_url_to_local_path_text, normalize_hash_location_suffix_fragment); called by 1 (render_local_link_target); 3 external calls (parse, Borrowed, decode).

fn normalize_hash_location_suffix_fragment(fragment: &str) -> Option<String>

Purpose: Normalizes a URL hash fragment that refers to source-code line or column locations.

Data flow: It receives a fragment such as L12C3, checks it against the location pattern, adds #, normalizes it, and returns it only if it is a recognized location.

Call relations: Local-link parsing uses this for file://...#L10 and similar path fragments.

Call graph: called by 1 (parse_local_link_target).

fn extract_colon_location_suffix(path_text: &str) -> Option<String>

Purpose: Extracts a trailing source-location suffix like :12 or :12:3 from a path string.

Data flow: It matches only a suffix at the end of the string and returns that suffix without disturbing other colons such as Windows drive letters.

Call relations: Local-link parsing uses this when no hash-style location was found.

Call graph: called by 1 (parse_local_link_target).

fn expand_local_link_path(path_text: &str) -> String

Purpose: Expands home-relative local paths and normalizes path separators for display.

Data flow: It receives path text, expands ~/ using the user's home directory when available, converts separators to the display form, and returns the normalized path.

Call relations: Local-link parsing calls this for plain path-like link destinations.

Call graph: calls 1 internal fn (normalize_local_link_path_text); called by 1 (parse_local_link_target); 1 external calls (home_dir).

fn file_url_to_local_path_text(url: &Url) -> Option<String>

Purpose: Converts a file:// URL into display-ready local path text.

Data flow: It receives a parsed URL, first tries the URL library's file-path conversion, then falls back to reconstructing UNC or Windows-like paths, and normalizes separators.

Call relations: Local-link parsing calls this for file URL destinations.

Call graph: calls 1 internal fn (normalize_local_link_path_text); called by 1 (parse_local_link_target); 5 external calls (host_str, path, to_file_path, format!, matches!).

fn normalize_local_link_path_text(path_text: &str) -> String

Purpose: Makes local path text stable for display across platforms.

Data flow: It receives path text, converts backslashes to forward slashes, and rewrites Windows UNC-style prefixes into //server/share form.

Call relations: Home expansion, file URL conversion, and display shortening all use this before comparing or showing paths.

Call graph: called by 3 (display_local_link_path, expand_local_link_path, file_url_to_local_path_text); 1 external calls (format!).

fn is_absolute_local_link_path(path_text: &str) -> bool

Purpose: Checks whether normalized local path text is absolute.

Data flow: It receives path text and returns true for Unix absolute paths, UNC paths, and Windows drive-rooted paths.

Call relations: Display path selection uses this to decide whether cwd-relative shortening is possible.

Call graph: called by 1 (display_local_link_path); 1 external calls (matches!).

fn trim_trailing_local_path_separator(path_text: &str) -> &str

Purpose: Removes trailing / characters from local paths without damaging root paths.

Data flow: It receives path text, preserves roots like /, //, and C:/, and otherwise trims trailing slashes.

Call relations: Prefix stripping uses this so /work/project/ and /work/project compare the same.

Call graph: called by 1 (strip_local_path_prefix); 1 external calls (matches!).

fn strip_local_path_prefix(path_text: &'a str, cwd_text: &str) -> Option<&'a str>

Purpose: Returns a path relative to the cwd when the path is strictly underneath that cwd.

Data flow: It receives normalized path text and cwd text, trims trailing separators, refuses to strip if they are equal, handles root cwd specially, and returns the remainder if it is a child path.

Call relations: Display path selection calls this to shorten absolute local links in the current session directory.

Call graph: calls 1 internal fn (trim_trailing_local_path_separator); called by 1 (display_local_link_path).

fn display_local_link_path(path_text: &str, cwd: Option<&Path>) -> String

Purpose: Chooses the visible path text for a local link.

Data flow: It normalizes the path, leaves relative paths unchanged, tries to shorten absolute paths under the provided cwd, and otherwise keeps the absolute path.

Call relations: Local-link target rendering calls this after parsing the path and before appending any line/column suffix.

Call graph: calls 3 internal fn (is_absolute_local_link_path, normalize_local_link_path_text, strip_local_path_prefix); called by 1 (render_local_link_target).

fn lines_to_strings(text: &Text<'_>) -> Vec<String>

Purpose: Converts rendered Text into plain strings so tests can compare visible output easily.

Data flow: It receives rendered text, joins each line's spans into one string, and returns a vector of line strings.

Call relations: Many wrapping tests call this after rendering Markdown.

fn wraps_plain_text_when_width_provided()

Purpose: Checks that ordinary prose wraps at the requested width.

Data flow: It renders a sentence with a small width, converts output to strings, and asserts the expected wrapped lines.

Call relations: The test harness runs this; it exercises the public width-aware renderer.

Call graph: calls 1 internal fn (render_markdown_text_with_width); 2 external calls (assert_eq!, lines_to_strings).

fn wraps_list_items_preserving_indent()

Purpose: Checks that a wrapped bullet list item keeps its continuation indentation.

Data flow: It renders one long list item, converts lines to strings, and compares them with the expected bullet and continuation lines.

Call relations: This test exercises list prefix calculation and wrapping together.

Call graph: calls 1 internal fn (render_markdown_text_with_width); 2 external calls (assert_eq!, lines_to_strings).

fn wraps_nested_lists()

Purpose: Checks wrapping for nested unordered lists.

Data flow: It renders nested list Markdown at a narrow width and asserts that both outer and inner continuation lines are indented correctly.

Call relations: This test covers the interaction between list nesting, markers, and line wrapping.

Call graph: calls 1 internal fn (render_markdown_text_with_width); 2 external calls (assert_eq!, lines_to_strings).

fn wraps_ordered_lists()

Purpose: Checks that ordered list numbers and continuation indentation survive wrapping.

Data flow: It renders a long numbered item, extracts strings, and asserts the expected lines.

Call relations: This test exercises ordered-list marker creation and prefix handling.

Call graph: calls 1 internal fn (render_markdown_text_with_width); 2 external calls (assert_eq!, lines_to_strings).

fn wraps_blockquotes()

Purpose: Checks that blockquote text wraps with > on each line.

Data flow: It renders a long quoted line with a narrow width and compares the visible output.

Call relations: This test covers blockquote prefixing and wrapping.

Call graph: calls 1 internal fn (render_markdown_text_with_width); 2 external calls (assert_eq!, lines_to_strings).

fn wraps_blockquotes_inside_lists()

Purpose: Checks that blockquotes nested inside list items keep both list and quote indentation.

Data flow: It renders a list item followed by an indented blockquote and asserts the expected wrapped strings.

Call relations: This test exercises combined list and blockquote indentation contexts.

Call graph: calls 1 internal fn (render_markdown_text_with_width); 2 external calls (assert_eq!, lines_to_strings).

fn wraps_list_items_containing_blockquotes()

Purpose: Checks ordered-list items that contain a blockquote.

Data flow: It renders an ordered list item with quoted text, converts to strings, and asserts the wrapped output.

Call relations: This test covers ordered-list prefixes together with nested blockquote prefixes.

Call graph: calls 1 internal fn (render_markdown_text_with_width); 2 external calls (assert_eq!, lines_to_strings).

fn does_not_wrap_code_blocks()

Purpose: Checks that code block lines are not wrapped even when a narrow width is given.

Data flow: It renders a fenced code block with a long line and asserts that the line remains intact.

Call relations: This test protects copy/paste-friendly code-block behavior in flush_current_line.

Call graph: calls 1 internal fn (render_markdown_text_with_width); 2 external calls (assert_eq!, lines_to_strings).

fn does_not_split_long_url_like_token_without_scheme()

Purpose: Checks that a long URL-like token without a scheme is not broken apart during wrapping.

Data flow: It renders one long path-like token, extracts lines, and asserts that the full token appears on a single line.

Call relations: This test exercises adaptive wrapping behavior used by normal text output.

Call graph: calls 1 internal fn (render_markdown_text_with_width); 2 external calls (assert_eq!, lines_to_strings).

fn fenced_code_info_string_with_metadata_highlights()

Purpose: Checks that fenced code blocks still get syntax highlighting when the info string includes extra metadata.

Data flow: It renders Rust code blocks with different info-string formats and asserts that some spans have RGB highlight colors.

Call relations: This test exercises language-token extraction in start_codeblock and highlighting in end_codeblock.

Call graph: calls 1 internal fn (render_markdown_text); 2 external calls (assert!, format!).

fn crlf_code_block_no_extra_blank_lines()

Purpose: Checks that CRLF-formatted code blocks do not gain extra blank lines.

Data flow: It renders a Rust code block with Windows-style line endings, converts lines to strings, and asserts exactly the original code lines.

Call relations: This test protects the code-buffer concatenation path in text and end_codeblock.

Call graph: calls 1 internal fn (render_markdown_text); 2 external calls (assert_eq!, lines_to_strings).

fn wrap_cell_preserves_hard_break_lines()

Purpose: Checks that table-cell hard breaks remain separate lines after wrapping.

Data flow: It builds a table cell with two internal lines, wraps it, converts the wrapped result to strings, and asserts both lines remain.

Call relations: This test directly exercises Writer::wrap_cell.

Call graph: 4 external calls (new, assert_eq!, empty, default).

fn make_cell(text: &str) -> TableCell

Purpose: Builds a plain one-line table cell for table unit tests.

Data flow: It receives text, creates an empty TableCell, pushes a raw span, and returns the cell.

Call relations: Column-metric and spillover tests use this helper to create table inputs.

Call graph: 2 external calls (raw, default).

fn make_body_row(cells: Vec<TableCell>, has_table_pipe_syntax: bool) -> TableBodyRow

Purpose: Builds a table body row for tests, including whether it used pipe syntax.

Data flow: It receives cells and a pipe-syntax flag, packages them into a TableBodyRow, and returns it.

Call relations: Spillover tests use this helper to create realistic row metadata.

fn column_classification_narrative_by_word_count()

Purpose: Checks that prose-heavy table columns are classified as narrative.

Data flow: It creates short ID cells and verbose description cells, collects metrics, and asserts the expected column kinds.

Call relations: This test directly exercises table column metric collection.

Call graph: 3 external calls (collect_table_column_metrics, assert_eq!, vec!).

fn column_classification_token_heavy_by_url_like_tokens()

Purpose: Checks that columns full of long URL-like tokens are classified as token-heavy.

Data flow: It builds a one-column table of long URLs, collects metrics, and asserts the token-heavy kind.

Call relations: This test protects the width-allocation priority for URL/path columns.

Call graph: 3 external calls (collect_table_column_metrics, assert_eq!, vec!).

fn column_classification_token_heavy_for_local_path_lists()

Purpose: Checks that columns containing long local file paths are treated as token-heavy.

Data flow: It builds cells containing multiple long file paths, collects metrics, and asserts the token-heavy classification.

Call relations: This test protects table layout behavior for file-list output.

Call graph: 3 external calls (collect_table_column_metrics, assert_eq!, vec!).

fn column_classification_compact_all_short()

Purpose: Checks that short status/count columns are classified as compact.

Data flow: It builds a table with short values, collects metrics, and asserts both columns are compact.

Call relations: This test protects the rule that compact columns should resist shrinking.

Call graph: 3 external calls (collect_table_column_metrics, assert_eq!, vec!).

fn preferred_floor_narrative_retains_readable_width()

Purpose: Checks the preferred minimum width for narrative columns.

Data flow: It creates sample narrative metrics and asserts the floor is readable but never larger than the column's maximum width.

Call relations: This test directly exercises preferred_column_floor for prose columns.

Call graph: 1 external calls (assert_eq!).

fn preferred_floor_token_heavy_retains_readable_width()

Purpose: Checks the preferred minimum width for token-heavy columns.

Data flow: It creates token-heavy metrics and asserts the floor keeps a modest readable width.

Call relations: This test covers one branch of table width allocation policy.

Call graph: 1 external calls (assert_eq!).

fn preferred_floor_compact_uses_body_token()

Purpose: Checks that compact column floors are based on header and body token widths with a cap.

Data flow: It creates compact metrics with different token sizes and asserts the computed floors.

Call relations: This test protects compact-column width behavior.

Call graph: 1 external calls (assert_eq!).

fn next_column_to_shrink_prefers_token_heavy_then_narrative()

Purpose: Checks the shrink priority used when a table is too wide.

Data flow: It creates three columns with different kinds, asks which should shrink, changes available slack, and asserts token-heavy shrinks before narrative and compact.

Call relations: This test directly exercises next_column_to_shrink.

Call graph: 2 external calls (next_column_to_shrink, assert_eq!).

fn spillover_detects_single_cell_row()

Purpose: Checks that a single-cell row without pipe syntax is treated as spillover prose.

Data flow: It builds such a row and asserts is_spillover_row returns true.

Call relations: This test protects the table parser-artifact cleanup heuristic.

Call graph: 3 external calls (assert!, make_body_row, vec!).

fn spillover_keeps_single_cell_row_with_table_pipe_syntax()

Purpose: Checks that an explicit single-cell pipe row is kept as table data.

Data flow: It builds a single-cell row marked as pipe syntax and asserts it is not spillover.

Call relations: This test keeps the spillover heuristic from removing real sparse tables.

Call graph: 3 external calls (assert!, make_body_row, vec!).

fn spillover_detects_html_content()

Purpose: Checks that sparse rows containing HTML-like text are treated as spillover.

Data flow: It builds a multi-cell row where only the first cell has HTML-like content and asserts spillover detection.

Call relations: This test covers HTML parser-artifact detection.

Call graph: 3 external calls (assert!, make_body_row, vec!).

fn spillover_detects_label_followed_by_html()

Purpose: Checks that an HTML block: label followed by HTML content is treated as spillover.

Data flow: It builds a label row and a following HTML row, then asserts the label row is spillover.

Call relations: This test covers the multi-row spillover heuristic.

Call graph: 3 external calls (assert!, make_body_row, vec!).

fn spillover_detects_trailing_html_label()

Purpose: Checks that a trailing HTML-intro label is treated as spillover even without a following row.

Data flow: It builds a sparse HTML block: row with no next row and asserts spillover detection.

Call relations: This test protects the trailing-label branch of is_spillover_row.

Call graph: 3 external calls (assert!, make_body_row, vec!).

fn spillover_keeps_normal_multi_cell_row()

Purpose: Checks that normal rows with multiple non-empty cells remain table rows.

Data flow: It builds a row with three non-empty cells and asserts it is not spillover.

Call relations: This test prevents over-aggressive spillover extraction.

Call graph: 3 external calls (assert!, make_body_row, vec!).

fn spillover_keeps_label_when_next_is_not_html()

Purpose: Checks that a sparse label row is kept when the following row is ordinary table data.

Data flow: It builds a Status: row followed by an ok row and asserts the first is not spillover.

Call relations: This test guards a subtle spillover false-positive case.

Call graph: 3 external calls (assert!, make_body_row, vec!).

fn annotates_explicit_web_link_label_and_visible_destination()

Purpose: Checks that explicit web links produce terminal hyperlink annotations for both the label and shown destination.

Data flow: It renders a Markdown link, collects all hyperlink annotations, and asserts their count and destination.

Call relations: This test exercises link handling through the hyperlink-aware line renderer.

Call graph: calls 1 internal fn (render_markdown_lines_with_width_and_cwd); 2 external calls (assert!, assert_eq!).

fn wrapped_table_url_fragments_keep_complete_web_destination()

Purpose: Checks that URLs wrapped across table lines keep the full hyperlink destination on every fragment.

Data flow: It renders a narrow table containing a long URL, selects linked output lines, and asserts every hyperlink still points to the full URL.

Call relations: This test covers table cell wrapping and hyperlink range remapping.

Call graph: calls 1 internal fn (render_markdown_lines_with_width_and_cwd); 2 external calls (assert!, format!).

fn key_value_table_keeps_web_annotations()

Purpose: Checks that table key/value fallback preserves web hyperlink annotations.

Data flow: It renders an intentionally narrow table that falls back to records, collects destinations, and asserts they all match the original URL.

Call relations: This test exercises the table fallback path used when aligned columns cannot fit.

Call graph: calls 1 internal fn (render_markdown_lines_with_width_and_cwd); 2 external calls (assert!, format!).

fn does_not_annotate_code_or_non_web_markdown_links()

Purpose: Checks that URLs inside code or non-web links are not auto-annotated as web hyperlinks.

Data flow: It renders inline code, block code, mail links, and table content, then asserts no hyperlink annotations are present.

Call relations: This test protects the conditions in normal and table text writing that suppress auto-linking.

Call graph: calls 1 internal fn (render_markdown_lines_with_width_and_cwd); 1 external calls (assert!).

fn pipe_table_fallback_keeps_web_annotations()

Purpose: Checks that raw pipe-table fallback preserves valid web annotations and does not annotate code URLs.

Data flow: It renders a table too narrow for aligned layout, gathers hyperlink destinations, and asserts expected web destinations are present while code-label URLs are absent.

Call relations: This test exercises render_table_pipe_fallback and row_to_pipe_line.

Call graph: calls 1 internal fn (render_markdown_lines_with_width_and_cwd); 2 external calls (assert!, format!).

fn append_markdown(
    markdown_source: &str,
    width: Option<usize>,
    cwd: Option<&Path>,
    lines: &mut Vec<Line<'static>>,
)

Purpose: This is the general Markdown rendering entry point. Code that already has ordinary Markdown uses it to turn that text into terminal-ready lines, optionally using a display width and a working directory for path formatting.

Data flow: It receives Markdown text, an optional width, an optional current working directory, and a mutable list of output lines. It asks the shared Markdown renderer to produce styled lines, then copies those owned rendered lines into the caller’s output list. The caller’s list is longer afterward; the function itself returns no separate value.

Call relations: This function sits between higher-level UI flows and the shared renderer. It is called by tests and by rendering paths such as completed streaming output and full-message rendering, then hands the heavy parsing work to render_markdown_text_with_width_and_cwd and the final line insertion to push_owned_lines.

Call graph: calls 2 internal fn (render_markdown_text_with_width_and_cwd, push_owned_lines); called by 13 (append_markdown_keeps_ordered_list_line_unsplit_in_context, append_markdown_matches_tui_markdown_for_ordered_item, append_markdown_preserves_full_text_line, citations_render_as_plain_text, indented_code_blocks_preserve_leading_whitespace, commit_complete_lines, finalize_and_drain, assert_streamed_equals_full, heading_not_inlined_when_split_across_chunks, loose_list_with_split_dashes_matches_full_render (+3 more)).

fn append_markdown_agent(
    markdown_source: &str,
    width: Option<usize>,
    lines: &mut Vec<Line<'static>>,
)

Purpose: This test-only helper renders agent messages while applying the special table-fence cleanup first. It exists so tests can check that agent replies display Markdown tables as tables instead of as code.

Data flow: It receives raw agent Markdown, an optional width, and a mutable output list. It first normalizes the text with unwrap_markdown_fences, then renders the normalized Markdown, then appends the resulting styled lines to the output list. The visible result is added to the supplied list.

Call relations: This function is called by many tests that exercise agent rendering. Its work is a small pipeline: unwrap likely table fences, render the Markdown, and push the rendered lines into the terminal line buffer.

Call graph: calls 3 internal fn (unwrap_markdown_fences, render_markdown_text_with_width_and_cwd, push_owned_lines); called by 20 (append_markdown_agent_keeps_markdown_fence_when_content_is_not_table, append_markdown_agent_keeps_non_markdown_fences_as_code, append_markdown_agent_unwraps_markdown_fences_for_no_outer_table_rendering, append_markdown_agent_unwraps_markdown_fences_for_single_column_table, append_markdown_agent_unwraps_markdown_fences_for_table_rendering, append_markdown_agent_unwraps_markdown_fences_for_two_column_no_outer_table, collector_source_chunks_round_trip_into_agent_fence_unwrapping, controller_handles_table_immediately_after_heading, controller_holds_blockquoted_table_tail_until_stable, controller_keeps_markdown_fenced_no_outer_tables_mutable_until_finalize (+10 more)).

fn render_markdown_agent_with_links_and_cwd(
    markdown_source: &str,
    width: Option<usize>,
    cwd: Option<&Path>,
) -> Vec<HyperlinkLine>

Purpose: This renders an agent message into lines that can include terminal hyperlinks. It also applies the same Markdown-table fence cleanup used for agent output.

Data flow: It receives raw agent Markdown, an optional width, and an optional working directory. It removes qualifying Markdown table fences, sends the cleaned text to the link-aware Markdown renderer, and returns a new vector of HyperlinkLine values ready for display.

Call relations: This function is used by display and streaming code that needs hyperlink-capable output. It prepares agent text with unwrap_markdown_fences, then delegates the actual rendering to render_markdown_lines_with_width_and_cwd.

Call graph: calls 2 internal fn (unwrap_markdown_fences, render_markdown_lines_with_width_and_cwd); called by 4 (display_hyperlink_lines, display_hyperlink_lines, render_source, stable_prefix_len_for_source_start).

fn unwrap_markdown_fences(markdown_source: &'a str) -> Cow<'a, str>

Purpose: This removes ``md or ``markdown fence markers only when the fenced content appears to contain a Markdown table. It protects normal code blocks while making agent-wrapped tables render properly.

Data flow: It receives a Markdown string. If there are no fence markers, it returns a borrowed reference to the original text without copying. Otherwise it scans line by line, tracks whether it is inside a fence, buffers possible Markdown-fence content by source ranges, checks for a table header followed by a delimiter row, and builds either the original text or a version with selected fence lines removed. It returns either the original borrowed text or a newly owned cleaned string.

Call relations: This is the cleanup step used before agent rendering. append_markdown_agent and render_markdown_agent_with_links_and_cwd call it before passing text to the Markdown renderer, and several tests call it directly to verify edge cases such as blockquotes, unfinished fences, and non-table content.

Call graph: called by 6 (append_markdown_agent, render_markdown_agent_with_links_and_cwd, append_markdown_agent_keeps_markdown_fence_with_blank_line_between_header_and_delimiter, append_markdown_agent_keeps_non_blockquoted_markdown_fence_with_blockquote_table_example, append_markdown_agent_unwraps_blockquoted_markdown_fence_table, unwrap_markdown_fences_repro_keeps_fence_without_header_delimiter_pair); 7 external calls (MarkdownCandidate, Passthrough, new, Borrowed, Owned, with_capacity, new).

fn lines_to_strings(lines: &[Line<'static>]) -> Vec<String>

Purpose: This helper turns rendered ratatui lines back into plain strings for easier test comparisons. It hides styling details so tests can focus on what text would be visible.

Data flow: It receives a slice of rendered Line values. For each line, it joins the text content of all spans into one string, then returns a vector of those strings.

Call relations: Most tests use this after calling append_markdown or append_markdown_agent. It converts styled output into simple text before assertions check the result.

Call graph: 1 external calls (iter).

fn citations_render_as_plain_text()

Purpose: This test checks that citation-like text with unusual brackets and symbols is preserved as normal visible text. It guards against the Markdown renderer accidentally interpreting or dropping citation markers.

Data flow: It builds a short source string containing two citation-looking references, renders it with append_markdown, converts the output lines to plain strings, and compares them with the expected original text.

Call relations: The test calls append_markdown to exercise the normal rendering path, then uses lines_to_strings to make the result easy to compare.

Call graph: calls 1 internal fn (append_markdown); 3 external calls (new, assert_eq!, lines_to_strings).

fn indented_code_blocks_preserve_leading_whitespace()

Purpose: This test verifies that indented code blocks keep their leading spaces. That matters because code indentation is part of what the user needs to see.

Data flow: It sends Markdown containing an indented code line through append_markdown. It converts the rendered lines to strings and checks that the code line still starts with four spaces and that surrounding blank lines remain.

Call relations: The test exercises append_markdown and uses lines_to_strings for comparison. It protects the normal Markdown rendering path from stripping meaningful whitespace.

Call graph: calls 1 internal fn (append_markdown); 3 external calls (new, assert_eq!, lines_to_strings).

fn append_markdown_preserves_full_text_line()

Purpose: This test checks that a long plain-text sentence stays as one rendered line when no width wrapping is requested. It prevents accidental splitting or loss of text in simple messages.

Data flow: It renders one plain text line with append_markdown, checks that only one output line was produced, joins all spans in that line, and compares the visible text with the expected sentence.

Call relations: The test calls append_markdown directly and inspects the returned line list. It focuses on the simplest rendering case: plain text in, plain text out.

Call graph: calls 1 internal fn (append_markdown); 2 external calls (new, assert_eq!).

fn append_markdown_matches_tui_markdown_for_ordered_item()

Purpose: This test verifies that a single ordered-list item displays as one readable line. It protects list formatting in the terminal UI.

Data flow: It renders the Markdown text '1. Tight item', converts the rendered line to a string, and checks that the output is exactly the same visible list item.

Call relations: The test calls append_markdown and lines_to_strings. It confirms the normal renderer keeps the number marker and item text together.

Call graph: calls 1 internal fn (append_markdown); 3 external calls (new, assert_eq!, lines_to_strings).

fn append_markdown_keeps_ordered_list_line_unsplit_in_context()

Purpose: This test checks that an ordered-list item remains one line even when it appears after other text. It guards against a bug where the number marker could be separated from the list item text.

Data flow: It renders a short paragraph followed by an ordered list item. It converts all rendered lines to strings, checks that '1. Tight item' appears, and checks that the output does not contain a marker-only line followed by the item text.

Call relations: The test uses append_markdown for the rendering path and lines_to_strings for inspection. It verifies list behavior in a more realistic surrounding context.

Call graph: calls 1 internal fn (append_markdown); 3 external calls (new, assert!, lines_to_strings).

fn append_markdown_agent_unwraps_markdown_fences_for_table_rendering()

Purpose: This test proves that a table inside a ```markdown fence is unwrapped and rendered as a real table. It checks the main reason the agent-specific cleanup exists.

Data flow: It sends a fenced Markdown table through append_markdown_agent, converts the output to strings, and checks for table-drawing characters and table cell text rather than raw pipe syntax.

Call relations: The test calls append_markdown_agent, which calls unwrap_markdown_fences before rendering. It confirms the cleanup and renderer cooperate to produce native table output.

Call graph: calls 1 internal fn (append_markdown_agent); 3 external calls (new, assert!, lines_to_strings).

fn append_markdown_agent_unwraps_markdown_fences_for_no_outer_table_rendering()

Purpose: This test checks that table text without leading and trailing outer pipe characters is still recognized inside a Markdown fence. It protects a common compact table style.

Data flow: It renders a ```md fenced table with three columns and no outer pipes. It then checks that the output contains table-drawing characters and formatted cell text, and that the raw header line is not shown as plain code.

Call relations: The test runs through append_markdown_agent and then inspects the rendered strings. It verifies that the fence unwrapping supports more than one table spelling style.

Call graph: calls 1 internal fn (append_markdown_agent); 3 external calls (new, assert!, lines_to_strings).

fn append_markdown_agent_unwraps_markdown_fences_for_two_column_no_outer_table()

Purpose: This test checks the same no-outer-pipe table style for a smaller two-column table. It makes sure the table detection is not tied only to wider examples.

Data flow: It sends a two-column fenced Markdown table through append_markdown_agent, converts output lines to strings, and checks for table formatting and row content while ensuring the raw header is not left visible.

Call relations: The test exercises append_markdown_agent and its call to unwrap_markdown_fences. It adds coverage for a simpler table shape.

Call graph: calls 1 internal fn (append_markdown_agent); 3 external calls (new, assert!, lines_to_strings).

fn append_markdown_agent_unwraps_markdown_fences_for_single_column_table()

Purpose: This test verifies that even a one-column Markdown table inside a Markdown fence can be unwrapped. It prevents table detection from assuming every table has multiple columns.

Data flow: It renders a fenced one-column table through append_markdown_agent, converts the output to strings, and checks that table formatting appears while the raw pipe header does not.

Call relations: The test uses the agent rendering path to confirm that unwrap_markdown_fences recognizes single-column tables before the Markdown renderer draws them.

Call graph: calls 1 internal fn (append_markdown_agent); 3 external calls (new, assert!, lines_to_strings).

fn append_markdown_agent_keeps_non_markdown_fences_as_code()

Purpose: This test makes sure non-Markdown code fences, such as ```rust, are not unwrapped even if their contents look like a table. That prevents real code examples from being misread as Markdown tables.

Data flow: It renders a Rust-fenced block containing table-like lines through append_markdown_agent. It converts the result to plain strings and checks that the three raw code lines are preserved.

Call relations: The test calls append_markdown_agent, which calls unwrap_markdown_fences. It verifies that the cleanup step only targets Markdown-labeled fences, not arbitrary code blocks.

Call graph: calls 1 internal fn (append_markdown_agent); 3 external calls (new, assert_eq!, lines_to_strings).

fn append_markdown_agent_unwraps_blockquoted_markdown_fence_table()

Purpose: This test checks that a Markdown table inside a blockquoted Markdown fence can still be unwrapped. A blockquote is Markdown text that starts with '>' to show quoted material.

Data flow: It passes a blockquoted fenced table directly to unwrap_markdown_fences and checks that the returned text no longer contains fence markers.

Call relations: Unlike many tests, this one calls unwrap_markdown_fences directly. It focuses on the cleanup logic’s ability to understand fences inside quoted text.

Call graph: calls 1 internal fn (unwrap_markdown_fences); 1 external calls (assert!).

fn append_markdown_agent_keeps_non_blockquoted_markdown_fence_with_blockquote_table_example()

Purpose: This test verifies a conservative edge case: a normal Markdown fence containing a blockquoted table example should stay fenced. It prevents the cleanup from changing examples that are meant to be shown as code.

Data flow: It passes a non-blockquoted ```markdown fence whose content lines are blockquoted table text into unwrap_markdown_fences. It checks that the returned text is exactly the original source.

Call relations: The test calls unwrap_markdown_fences directly. It confirms that the function distinguishes a blockquoted fence from a plain fence containing blockquoted-looking content.

Call graph: calls 1 internal fn (unwrap_markdown_fences); 1 external calls (assert_eq!).

fn append_markdown_agent_keeps_markdown_fence_when_content_is_not_table()

Purpose: This test checks that a Markdown fence without a table remains a code block. It protects intentional examples like fenced 'bold' from being rendered as real bold text.

Data flow: It renders a ```markdown block containing bold Markdown syntax through append_markdown_agent. After converting output to strings, it expects to see the literal text 'bold'.

Call relations: The test goes through append_markdown_agent and therefore through unwrap_markdown_fences. It proves that Markdown-labeled fences are only removed when their contents look like a table.

Call graph: calls 1 internal fn (append_markdown_agent); 3 external calls (new, assert_eq!, lines_to_strings).

fn unwrap_markdown_fences_repro_keeps_fence_without_header_delimiter_pair()

Purpose: This regression test checks that table-like lines are not enough to trigger unwrapping unless there is a proper header line immediately followed by a delimiter line. It avoids false positives.

Data flow: It passes a Markdown fence with a header-looking row, a non-delimiter line, and then a delimiter-looking row into unwrap_markdown_fences. It checks that the output exactly matches the input.

Call relations: The test calls unwrap_markdown_fences directly. It locks in the rule that table detection requires the right neighboring line pattern.

Call graph: calls 1 internal fn (unwrap_markdown_fences); 1 external calls (assert_eq!).

fn append_markdown_agent_keeps_markdown_fence_with_blank_line_between_header_and_delimiter()

Purpose: This test verifies that a blank line between a table header and delimiter prevents unwrapping. It keeps the table detector strict and predictable.

Data flow: It passes a fenced Markdown block with a blank line between the header row and delimiter row into unwrap_markdown_fences. It expects the function to return the original text unchanged.

Call relations: The test calls unwrap_markdown_fences directly. It protects the conservative behavior that only clear, valid table patterns are unwrapped.

Call graph: calls 1 internal fn (unwrap_markdown_fences); 1 external calls (assert_eq!).

fn new(width: Option<usize>, cwd: &Path) -> Self

Purpose: Creates a fresh collector for one stream of markdown text. It starts with an empty buffer and no committed text, and in tests it also remembers the current directory so local file links render consistently.

Data flow: It receives an optional display width and a current directory path. It stores the width, creates an empty text buffer, sets the committed position to zero, and in test builds copies the directory path. The result is a ready-to-use MarkdownStreamCollector.

Call relations: Test helpers and many tests call this at the start of a simulated stream. In production-style flow, this is the first step before chunks are fed in with push_delta and later released with commit or finalize methods.

Call graph: called by 9 (simulate_stream_markdown_for_tests, collector_source_chunks_round_trip_into_agent_fence_unwrapping, finalize_commits_partial_line, heading_not_inlined_when_split_across_chunks, heading_starts_on_new_line_when_following_paragraph, no_commit_until_newline, pipe_text_without_table_prefix_is_not_delayed, table_header_commits_without_holdback, new); 2 external calls (to_path_buf, new).

fn set_width(&mut self, width: Option<usize>)

Purpose: Changes the width used by the test-only rendering helpers. This lets tests simulate a terminal width change without rebuilding the collector.

Data flow: It receives a new optional width and replaces the collector’s stored width with it. Nothing is returned, and the buffered markdown text is not changed.

Call relations: This method is part of the collector’s support API. The provided call graph does not show a caller here, but it is meant to affect later test rendering done by commit_complete_lines or finalize_and_drain.

fn clear(&mut self)

Purpose: Resets the collector so it can be reused for another stream. It removes all buffered text and forgets what had been committed.

Data flow: It takes the collector’s current buffer and bookkeeping state, empties the buffer, resets the committed byte count to zero, and in tests resets the committed rendered line count too. It returns nothing.

Call relations: finalize_and_drain_source and finalize_and_drain call this after they flush the final content. It is the cleanup step that prevents old streamed text from leaking into the next stream.

Call graph: called by 3 (finalize_and_drain, finalize_and_drain_source, clear).

fn push_delta(&mut self, delta: &str)

Purpose: Adds one newly arrived piece of markdown text to the collector. A “delta” here means a small chunk of streamed output.

Data flow: It receives a text slice, writes a trace log for debugging, and appends the text to the end of the internal buffer. It returns nothing; the collector now contains more source text.

Call relations: Stream simulations and real stream controllers call this whenever new text arrives. After a pushed delta contains a newline, callers usually ask commit_complete_source or, in tests, commit_complete_lines for the newly completed part.

Call graph: 1 external calls (trace!).

fn commit_complete_source(&mut self) -> Option<String>

Purpose: Returns only the new raw markdown text that is safely complete, ending at the most recent newline. If no new complete line exists, it returns nothing.

Data flow: It looks inside the buffer for the last newline. If there is no newline, or if all text up to that newline was already committed earlier, it returns None. Otherwise it copies the newly completed slice, advances the committed byte position, and returns that slice as a string.

Call relations: This is the production-facing commit point used by stream controllers and exercised by collector_source_chunks_round_trip_into_agent_fence_unwrapping. It deliberately hands off raw source rather than rendered lines, so later rendering can be done with the full accumulated markdown context.

fn finalize_and_drain_source(&mut self) -> String

Purpose: Flushes the last uncommitted raw markdown when a stream ends. This covers the common case where the final line does not end with a newline.

Data flow: It compares the committed byte position with the buffer length. If nothing remains, it clears the collector and returns an empty string. If text remains, it copies that tail, adds a newline when missing, clears the collector, and returns the final source chunk.

Call relations: Callers use this after the stream is truly complete, or when intentionally consolidating interrupted output. It calls clear as its cleanup step, so it should not be used while more chunks from the same stream are expected.

Call graph: calls 1 internal fn (clear); 1 external calls (new).

fn commit_complete_lines(&mut self) -> Vec<Line<'static>>

Purpose: In test builds, renders the completed part of the buffered markdown and returns only the newly completed display lines. This helps tests check streaming behavior without involving the full stream controller.

Data flow: It finds the latest newline and renders the buffer up to that point with append_markdown. It trims a final spaces-only blank line from the count, compares the rendered line count with what was already returned, and returns only the new lines. It also updates both the committed source position and committed line count.

Call relations: The stream simulation helper and many tests call this after chunks that contain newlines. It hands raw completed source to the markdown renderer, then filters the rendered result down to just the new portion being tested.

Call graph: calls 2 internal fn (append_markdown, is_blank_line_spaces_only); 2 external calls (as_path, new).

fn finalize_and_drain(&mut self) -> Vec<Line<'static>>

Purpose: In test builds, renders and returns any display lines that remain when a simulated stream finishes. It makes sure even an unfinished last line is shown at the end.

Data flow: It copies the full buffer, adds a temporary newline if needed, logs debug information, renders the source with append_markdown, and returns only rendered lines that were not already committed. Then it clears the collector.

Call relations: simulate_stream_markdown_for_tests calls this when a test asks to finalize the stream. Like finalize_and_drain_source, it is an end-of-stream operation and uses clear to reset state afterward.

Call graph: calls 2 internal fn (append_markdown, clear); 4 external calls (as_path, new, debug!, trace!).

fn test_cwd() -> PathBuf

Purpose: Provides a stable current directory for tests. This avoids tying expected output to a particular operating system root path.

Data flow: It reads the system temporary directory path and returns it as a PathBuf, which is an owned path value. It does not change global state.

Call relations: simulate_stream_markdown_for_tests uses this when creating a collector, and many tests use it through that helper or directly. It supports predictable rendering of local file links in test-only markdown rendering.

Call graph: called by 1 (simulate_stream_markdown_for_tests); 1 external calls (temp_dir).

fn simulate_stream_markdown_for_tests(
    deltas: &[&str],
    finalize: bool,
) -> Vec<Line<'static>>

Purpose: Runs a small fake markdown stream for tests. It feeds chunks into a collector the same way real streamed output would arrive, then gathers the rendered lines.

Data flow: It receives a list of text chunks and a flag saying whether to finalize. It creates a collector, pushes each chunk, commits rendered lines whenever a chunk contains a newline, optionally drains the final remainder, and returns all collected rendered lines.

Call relations: Many tests use this as their main harness. It calls MarkdownStreamCollector::new, push_delta, commit_complete_lines, and sometimes finalize_and_drain, so individual tests can focus on expected output rather than repeating stream setup.

Call graph: calls 2 internal fn (new, test_cwd); called by 6 (assert_streamed_equals_full, empty_fenced_block_is_dropped_and_separator_preserved_before_heading, loose_list_with_split_dashes_matches_full_render, loose_vs_tight_list_items_streaming_matches_full, paragraph_then_empty_fence_then_heading_keeps_heading_on_new_line, utf8_boundary_safety_and_wide_chars); 1 external calls (new).

async fn no_commit_until_newline()

Purpose: Checks the collector’s central rule: do not release streamed markdown until a newline arrives. This prevents half-finished lines from being rendered too early.

Data flow: It creates a collector, pushes text without a newline, and confirms no lines are emitted. Then it pushes the newline that completes the line and confirms exactly one line is emitted.

Call relations: This test directly exercises MarkdownStreamCollector::new, push_delta, and commit_complete_lines. It verifies the behavior that stream controllers rely on before they re-render completed markdown.

Call graph: calls 1 internal fn (new); 3 external calls (assert!, assert_eq!, test_cwd).

async fn finalize_commits_partial_line()

Purpose: Checks that the final unfinished line is not lost when a stream ends. A response may end without a trailing newline, and users still need to see that text.

Data flow: It creates a collector, pushes a line without a newline, finalizes the collector, and asserts that one rendered line comes out. The collector is drained as part of finalization.

Call relations: This test focuses on finalize_and_drain. It complements the newline rule by proving that the rule is relaxed only at the true end of the stream.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, test_cwd).

async fn e2e_stream_blockquote_simple_is_green()

Purpose: Checks that a simple streamed blockquote is rendered with the expected green style. A blockquote is markdown text that starts with >.

Data flow: It simulates a stream containing one blockquote line, collects the rendered output, and inspects the line’s foreground color. The expected result is one green line.

Call relations: This test uses simulate_stream_markdown_for_tests, which exercises the collector and markdown renderer together. It protects the connection between streaming boundaries and blockquote styling.

Call graph: 2 external calls (assert_eq!, simulate_stream_markdown_for_tests).

async fn e2e_stream_blockquote_nested_is_green()

Purpose: Checks that nested blockquotes keep the same green styling when streamed. Nested blockquotes use repeated > markers.

Data flow: It simulates two blockquote lines, filters away blank quote-only lines that may appear around paragraphs, and confirms both meaningful lines are green. The output is used only for assertions.

Call relations: This test relies on simulate_stream_markdown_for_tests to drive the collector. It makes sure streaming does not break styling for multiple quote levels.

Call graph: 2 external calls (assert_eq!, simulate_stream_markdown_for_tests).

async fn e2e_stream_blockquote_with_list_items_is_green()

Purpose: Checks that list items inside a blockquote are still styled as blockquotes. This matters because nested markdown features can easily lose the parent style.

Data flow: It simulates two quoted bullet-list lines, receives rendered lines, and asserts that each line’s foreground color is green.

Call relations: The test goes through the stream simulation helper, so it tests the collector and renderer together. It catches regressions where list rendering might override quote coloring.

Call graph: 2 external calls (assert_eq!, simulate_stream_markdown_for_tests).

async fn e2e_stream_nested_mixed_lists_ordered_marker_is_light_blue()

Purpose: Checks styling for a deeply nested ordered-list marker in streamed markdown. An ordered-list marker is text like 1. at the start of a numbered item.

Data flow: It streams a mixed numbered and bullet list, searches the rendered lines for the third-level ordered item, and checks that at least one span on that line is light blue. A span is a styled piece of a terminal line.

Call relations: This test uses the stream simulation helper and then inspects the rendered result. It protects the visual styling rules for nested list markers during incremental rendering.

Call graph: 2 external calls (assert!, simulate_stream_markdown_for_tests).

async fn e2e_stream_blockquote_wrap_preserves_green_style()

Purpose: Checks that a long blockquote keeps its green style after word wrapping. Word wrapping means splitting a long visual line across terminal-width lines.

Data flow: It simulates a long quoted line, wraps the rendered output to a narrow width, removes blank lines, and confirms every wrapped piece begins with green styling.

Call relations: The test starts with simulate_stream_markdown_for_tests and then hands the output to word_wrap_lines. It verifies that styling survives both streaming and later terminal wrapping.

Call graph: calls 2 internal fn (new, word_wrap_lines); 3 external calls (assert!, assert_eq!, simulate_stream_markdown_for_tests).

async fn heading_starts_on_new_line_when_following_paragraph()

Purpose: Checks that a heading streamed after a paragraph starts on its own line. Without this, the display could wrongly glue a heading to the previous paragraph.

Data flow: It pushes a paragraph line and commits it, then pushes a heading line and commits again. It converts rendered lines to plain text and verifies the first commit contains the paragraph, while the second contains a blank separator and the heading.

Call relations: This test uses the collector directly instead of the simulation helper, so it can inspect each commit separately. It guards the incremental behavior around paragraph-to-heading transitions.

Call graph: calls 1 internal fn (new); 2 external calls (assert_eq!, test_cwd).

async fn heading_not_inlined_when_split_across_chunks()

Purpose: Checks a harder heading case where the newline and heading text arrive in separate chunks. The heading should still not be merged into the previous sentence.

Data flow: It pushes a paragraph without a newline and confirms nothing commits. Then it pushes a newline plus the start of a heading, commits only the completed paragraph, pushes the final heading newline, and confirms the heading appears separately. It also renders a simple full markdown line as a sanity check.

Call relations: This test directly drives MarkdownStreamCollector and also calls append_markdown for comparison. It proves the collector’s newline boundary rule works even when markdown syntax is split across chunks.

Call graph: calls 2 internal fn (append_markdown, new); 4 external calls (new, assert!, assert_eq!, test_cwd).

fn lines_to_plain_strings(lines: &[ratatui::text::Line<'_>]) -> Vec<String>

Purpose: Turns styled terminal lines into plain strings for easier test comparisons. It ignores colors and other style information.

Data flow: It receives rendered Line values, walks through each line’s spans, joins their text content, and returns a vector of plain strings.

Call relations: Many tests call this after using the collector or markdown renderer. It is a small test utility that lets assertions compare readable text instead of full styled structures.

Call graph: 1 external calls (iter).

async fn table_header_commits_without_holdback()

Purpose: Checks that table-like markdown lines continue to commit as newlines arrive. The collector itself should not delay table rows using special table rules.

Data flow: It pushes a table header, delimiter, body row, and blank line in sequence. After each important push, it commits rendered lines and confirms output continues to appear.

Call relations: This test calls the collector directly and uses lines_to_plain_strings for assertions. It confirms that table-specific waiting behavior, if any, belongs outside this collector.

Call graph: calls 1 internal fn (new); 4 external calls (assert!, assert_eq!, test_cwd, lines_to_plain_strings).

async fn pipe_text_without_table_prefix_is_not_delayed()

Purpose: Checks that ordinary text containing pipe characters is not mistaken for a table and delayed. A pipe is the | character often used in markdown tables.

Data flow: It pushes one completed text line containing pipes, commits it, converts the output to plain text, and asserts the line appears immediately.

Call relations: This test uses the collector directly and relies on lines_to_plain_strings to compare output. It reinforces that the collector commits by newline, not by guessing markdown table structure.

Call graph: calls 1 internal fn (new); 3 external calls (assert_eq!, test_cwd, lines_to_plain_strings).

async fn lists_and_fences_commit_without_duplication()

Purpose: Checks that streamed lists and fenced code blocks do not duplicate lines compared with rendering the full markdown at once. A fenced code block is text surrounded by lines like triple backticks.

Data flow: It passes list chunks and code-fence chunks to assert_streamed_equals_full. That helper compares streamed rendering with full rendering.

Call relations: This test delegates the detailed work to tests::assert_streamed_equals_full. It captures two common markdown structures where incremental rendering can easily repeat content.

Call graph: 1 external calls (assert_streamed_equals_full).

async fn utf8_boundary_safety_and_wide_chars()

Purpose: Checks that streamed Unicode text is not cut, duplicated, or corrupted. This includes emoji, East Asian characters, control characters, and combining marks.

Data flow: It defines a full Unicode input and a list of chunks that split that input in realistic places. It renders the chunks through the streaming helper, renders the full input directly with append_markdown, converts both to plain strings, and asserts they match.

Call relations: This test connects simulate_stream_markdown_for_tests, append_markdown, and lines_to_plain_strings. It protects against byte-position bookkeeping bugs in the collector.

Call graph: calls 2 internal fn (append_markdown, simulate_stream_markdown_for_tests); 5 external calls (new, assert_eq!, test_cwd, lines_to_plain_strings, vec!).

async fn e2e_stream_deep_nested_third_level_marker_is_light_blue()

Purpose: Checks exactly how a third-level ordered-list marker is styled in streamed output. It also confirms the following item text keeps the default color.

Data flow: It streams a deep mixed list, finds the line containing the third-level ordered item, checks that the first span is light blue, and then checks that the first real content span after the marker has no special foreground color.

Call relations: This test uses simulate_stream_markdown_for_tests and lines_to_plain_strings for diagnostics. It is a more precise version of the nested-list styling test.

Call graph: 4 external calls (assert!, assert_eq!, simulate_stream_markdown_for_tests, lines_to_plain_strings).

async fn empty_fenced_block_is_dropped_and_separator_preserved_before_heading()

Purpose: Checks that an empty fenced code block does not render visible fence markers, while a following heading still appears properly. Empty code fences should not clutter the terminal display.

Data flow: It streams an empty fenced block followed by a heading, finalizes, converts output to plain text, and asserts that no line contains fence markers while the heading is present.

Call relations: This test uses simulate_stream_markdown_for_tests and lines_to_plain_strings. It protects the interaction between stream boundaries, empty code blocks, and heading placement.

Call graph: calls 1 internal fn (simulate_stream_markdown_for_tests); 3 external calls (assert!, lines_to_plain_strings, vec!).

async fn paragraph_then_empty_fence_then_heading_keeps_heading_on_new_line()

Purpose: Checks that an empty fenced code block between a paragraph and a heading does not cause the heading to merge with the paragraph.

Data flow: It streams a paragraph, an empty fence, and a heading. It converts rendered output to plain text, finds the paragraph and heading positions, and asserts the heading comes later.

Call relations: This test uses the stream simulation helper for the full incremental path. It focuses on layout order rather than exact styling.

Call graph: calls 1 internal fn (simulate_stream_markdown_for_tests); 4 external calls (assert!, panic!, lines_to_plain_strings, vec!).

async fn loose_list_with_split_dashes_matches_full_render()

Purpose: Checks a previously problematic case where a loose list and a split dash could produce mismatched streamed output. A loose list has blank lines between parts of list items.

Data flow: It streams two chunks, including one ending in a lone dash, and collects the streamed plain strings. It also joins the chunks into one full markdown string, renders that directly, and asserts both results match.

Call relations: This test uses simulate_stream_markdown_for_tests, append_markdown, and lines_to_plain_strings. It protects against dangling list-marker artifacts during finalization.

Call graph: calls 2 internal fn (append_markdown, simulate_stream_markdown_for_tests); 5 external calls (new, assert_eq!, test_cwd, lines_to_plain_strings, vec!).

async fn loose_vs_tight_list_items_streaming_matches_full()

Purpose: Checks a realistic streamed section mixing tight and loose numbered lists. Tight lists have no blank paragraphs inside items; loose lists do.

Data flow: It feeds many small chunks into the stream simulator, converts the result to plain strings, also performs a full render for diagnostics, and asserts the streamed strings match an exact expected list of lines.

Call relations: This test is driven by simulate_stream_markdown_for_tests and uses direct markdown rendering as backup context. It guards against subtle list numbering, indentation, and paragraph-spacing regressions.

Call graph: calls 2 internal fn (append_markdown, simulate_stream_markdown_for_tests); 5 external calls (new, assert_eq!, test_cwd, lines_to_plain_strings, vec!).

async fn assert_streamed_equals_full(deltas: &[&str])

Purpose: Provides a shared test check: streamed rendering must match rendering the complete markdown all at once. This is the main comparison helper for fuzz-derived tests.

Data flow: It receives chunks, renders them through simulate_stream_markdown_for_tests, joins them into one full string, renders that full string with append_markdown, converts both outputs to plain strings, and asserts equality.

Call relations: Several tests call this helper instead of repeating the comparison logic. It ties the collector’s incremental behavior back to the expected full-render behavior.

Call graph: calls 2 internal fn (append_markdown, simulate_stream_markdown_for_tests); 4 external calls (new, assert_eq!, test_cwd, lines_to_plain_strings).

async fn fuzz_class_bullet_duplication_variant_1()

Purpose: Checks one fuzz-found bullet-list case that previously risked duplicated output. Fuzzing means testing with many generated or unusual inputs to find edge cases.

Data flow: It sends a small set of split bullet-list chunks to assert_streamed_equals_full. The assertion passes only if streamed and full rendering produce the same plain lines.

Call relations: This test delegates to tests::assert_streamed_equals_full. It preserves a specific regression case so future changes do not reintroduce the bug.

Call graph: 1 external calls (assert_streamed_equals_full).

async fn fuzz_class_bullet_duplication_variant_2()

Purpose: Checks a second fuzz-found bullet-list duplication case. It covers a different split point inside list text.

Data flow: It passes the chunk sequence to assert_streamed_equals_full, which compares streamed rendering against full rendering. The test itself returns no data beyond pass or fail.

Call relations: Like the first fuzz variant, this is a compact regression test built on the shared comparison helper.

Call graph: 1 external calls (assert_streamed_equals_full).

async fn streaming_html_block_then_text_matches_full()

Purpose: Checks that an HTML block followed by normal text streams the same way it renders as a complete document. Markdown often allows raw HTML blocks, which can affect surrounding parsing.

Data flow: It sends chunks containing a label, an inline HTML block line, and following text to assert_streamed_equals_full. The helper compares streamed and full plain-text output.

Call relations: This test delegates to the shared streamed-versus-full helper. It makes sure newline-based committing does not mis-handle markdown’s HTML block rules.

Call graph: 1 external calls (assert_streamed_equals_full).

async fn table_like_lines_inside_fenced_code_are_not_held()

Purpose: Checks that table-looking text inside a code block is treated as code, not as a real markdown table waiting for more rows. This matters for snippets that contain pipe characters.

Data flow: It streams an opening code fence, a pipe-separated line, and a closing fence through assert_streamed_equals_full. The streamed result must match full rendering.

Call relations: This test uses the shared comparison helper. It protects the boundary between code-fence parsing and table-like text.

Call graph: 1 external calls (assert_streamed_equals_full).

async fn collector_source_chunks_round_trip_into_agent_fence_unwrapping()

Purpose: Checks the production-style raw source path used with agent markdown rendering. It verifies that chunks emitted by the collector can later be rendered with agent-specific markdown fence unwrapping.

Data flow: It streams a markdown-fenced table through MarkdownStreamCollector, collecting raw source chunks with commit_complete_source and finalize_and_drain_source. It then renders the combined source with append_markdown_agent, converts output to plain strings, and asserts that a table separator appears while the raw table header does not.

Call relations: This test directly exercises the raw-source commit API rather than the test-only line API. It shows how stream controllers can collect safe source chunks first, then hand the accumulated markdown to the agent renderer for final display behavior.

Call graph: calls 2 internal fn (append_markdown_agent, new); 5 external calls (new, new, assert!, test_cwd, lines_to_plain_strings).

fn new(width: Option<usize>, cwd: &Path) -> Self

Purpose: Creates a fresh streaming state for one active stream. It prepares the markdown collector with the terminal width and current working directory, so local file links can be rendered correctly.

Data flow: It receives an optional display width and a filesystem path for the current directory. It builds a new markdown collector from those values, starts with an empty line queue, marks that no streamed text has arrived yet, and returns the ready-to-use StreamState.

Call relations: This is the starting point for code that needs a streaming buffer. Higher-level setup code calls it when creating stream-related state, and the test in this file also uses it to create a small queue for checking drain behavior.

Call graph: calls 1 internal fn (new); called by 2 (new, drain_n_clamps_to_available_lines); 1 external calls (new).

fn clear(&mut self)

Purpose: Resets the whole streaming state so it can be reused for the next stream. This clears both the partially collected markdown and any finished lines still waiting in the queue.

Data flow: It takes an existing mutable StreamState. It tells the markdown collector to forget its current content, empties the queued display lines, resets the “seen any delta yet” flag, and returns nothing.

Call relations: It is used by reset logic when a stream lifecycle ends or restarts. Rather than creating separate cleanup steps in multiple places, callers can ask this method to put the stream state back into its initial empty condition.

Call graph: calls 1 internal fn (clear); called by 1 (reset); 1 external calls (clear).

fn step(&mut self) -> Vec<HyperlinkLine>

Purpose: Takes one finished line from the front of the queue for display. It is the smallest possible drain operation: reveal at most one queued line.

Data flow: It reads the front of the queued-lines list. If a line is waiting, it removes that one item and returns it inside a vector; if the queue is empty, it returns an empty vector. The queue is changed only by removing that first item.

Call relations: The streaming tick logic calls this when it wants to advance the transcript one line at a time. This method does not decide when a tick should happen; it simply performs the safe, ordered removal requested by that outer controller.

Call graph: called by 1 (tick); 1 external calls (pop_front).

fn drain_n(&mut self, max_lines: usize) -> Vec<HyperlinkLine>

Purpose: Takes several finished lines from the front of the queue, up to a requested maximum. This lets the UI catch up faster when many lines are waiting.

Data flow: It receives a maximum number of lines to remove. It compares that number with the actual queue length, drains only the available amount, converts the stored queue entries back into plain HyperlinkLine values, and returns them in their original order.

Call relations: Batch ticking code calls this when policy has decided that more than one line should be committed at once. The method protects callers from asking for too much by automatically clamping the request to the number of queued lines.

Call graph: called by 1 (tick_batch); 2 external calls (drain, len).

fn clear_queue(&mut self)

Purpose: Empties only the committed-line queue while leaving the markdown collector and stream lifecycle flags alone. This is useful when the already-rendered queue must be rebuilt without pretending the whole stream restarted.

Data flow: It receives mutable access to the state, removes every queued line, and returns nothing. The collector and has_seen_delta flag stay as they were.

Call relations: Rendering code calls this while rebuilding or synchronizing stable output, and when display settings such as render mode or width change. Those callers can discard stale queued lines and then refill the queue from a freshly rendered view.

Call graph: called by 4 (rebuild_stable_queue_from_render, set_render_mode, set_width, sync_stable_queue); 1 external calls (clear).

fn is_idle(&self) -> bool

Purpose: Answers whether there are no finished lines waiting to be committed to the transcript. Callers use it to know whether the streaming queue has work left.

Data flow: It reads the queued-lines list and checks whether it is empty. It returns true if nothing is waiting and false otherwise, without changing the state.

Call relations: Outer idle-checking code calls this as part of deciding whether the stream still needs display work. It acts as a simple status light for the queue.

Call graph: called by 1 (is_idle); 1 external calls (is_empty).

fn queued_len(&self) -> usize

Purpose: Reports how many finished lines are currently waiting in the queue. This helps other code make pacing decisions, such as whether to drain slowly or catch up.

Data flow: It reads the queue length and returns that number. It does not remove or add any lines.

Call relations: Queue-inspection and rendering-adjustment code calls this when it needs to understand current backlog pressure. For example, width or render-mode changes can use this count while rebuilding or synchronizing queued output.

Call graph: called by 4 (queued_lines, set_render_mode, set_width, sync_stable_queue); 1 external calls (len).

fn oldest_queued_age(&self, now: Instant) -> Option<Duration>

Purpose: Reports how long the oldest queued line has been waiting. This gives timing policy code a way to avoid leaving old output stuck in the queue.

Data flow: It receives the current time from the caller. It looks at the front queue entry, compares that entry’s stored enqueue time with the provided time, and returns the elapsed duration. If the queue is empty, it returns no value.

Call relations: Higher-level age-checking code calls this when deciding whether queued text should be committed soon. This method supplies the timing fact; policy code elsewhere decides what to do with it.

Call graph: called by 1 (oldest_queued_age); 1 external calls (front).

fn enqueue(&mut self, lines: Vec<HyperlinkLine>)

Purpose: Adds newly completed display lines to the back of the queue. All lines added together receive the same timestamp, showing when that batch became ready.

Data flow: It receives a vector of HyperlinkLine values. It records the current time once, wraps each line with that timestamp, appends the wrapped entries to the queue, and returns nothing.

Call relations: Render rebuilding and queue synchronization code call this after they have produced committed lines. This method is the single place where those lines enter the FIFO queue, preserving arrival order for later drains.

Call graph: called by 2 (rebuild_stable_queue_from_render, sync_stable_queue); 2 external calls (now, extend).

fn test_cwd() -> PathBuf

Purpose: Provides a stable current-directory path for tests. The tests only need an absolute-looking directory value, not a project-specific folder.

Data flow: It reads the operating system’s temporary directory path and returns it as a PathBuf. It does not touch the streaming state.

Call relations: The queue-draining test calls this while constructing a StreamState. Using the temporary directory keeps the test from depending on Unix or Windows root-path details.

Call graph: 1 external calls (temp_dir).

fn drain_n_clamps_to_available_lines()

Purpose: Checks that asking to drain more lines than exist does not fail or invent extra output. It proves that drain_n safely returns only the queued lines that are actually available.

Data flow: It creates a new stream state, enqueues one line containing the text “one,” then asks to drain up to eight lines. The result should contain exactly that one line, and the queue should be empty afterward.

Call relations: This test exercises StreamState::new, StreamState::enqueue, StreamState::drain_n, and StreamState::is_idle together. It protects the batch-drain behavior used by tick-batch code from accidentally over-reading the queue.

Call graph: calls 1 internal fn (new); 4 external calls (assert!, assert_eq!, test_cwd, vec!).

fn new(width: Option<usize>, cwd: &Path, render_mode: HistoryRenderMode) -> Self

Purpose: Creates the shared streaming engine for one answer or plan. It records the current render width, working directory, render mode, and empty buffers for incoming text and rendered lines.

Data flow: It receives an optional width, a current-directory path, and a render mode. It builds a fresh StreamState, empty source string, empty rendered-line list, counters set to zero, and a new table holdback scanner. The result is a ready-to-use StreamCore.

Call relations: The two public controllers call this when they are created, so both agent-message streams and plan streams start with the same bookkeeping rules.

Call graph: calls 2 internal fn (new, new); called by 2 (new, new); 3 external calls (to_path_buf, with_capacity, with_capacity).

fn push_delta(&mut self, delta: &str) -> bool

Purpose: Accepts the next piece of streamed text and decides whether any newly complete lines can be queued for display. It deliberately waits for newlines before committing source, so unfinished rows or paragraphs do not flash incorrectly.

Data flow: A text delta goes in. The collector stores it, and if the delta completes one or more newline-ended chunks, those chunks are appended to raw_source, scanned for table structure, re-rendered, and compared with the current stable boundary. It returns true when new stable lines were added to the animation queue.

Call relations: StreamController::push and PlanStreamController::push hand incoming stream text here. This function then calls the render refresh and stable-queue sync paths that drive later commit ticks.

Call graph: calls 3 internal fn (recompute_streaming_render, sync_stable_queue, push_source_chunk); called by 2 (push, push).

fn finalize_remaining(&mut self) -> Vec<HyperlinkLine>

Purpose: Finishes a stream and returns every rendered line that has not already been emitted. It produces the final canonical rendering instead of trying to stitch together old queued lines and live tail lines.

Data flow: It drains any leftover uncommitted source from the collector, appends and scans it, renders the full raw source, then slices off the lines already emitted. The output is a list of remaining hyperlink-aware terminal lines.

Call relations: Both controllers call this during finalize. The remaining lines are then wrapped into the appropriate history cell by each controller’s emit method.

Call graph: calls 2 internal fn (render_source, push_source_chunk); called by 2 (finalize, finalize); 1 external calls (new).

fn tick(&mut self) -> Vec<HyperlinkLine>

Purpose: Advances the commit animation by one step. In practice, it releases the next queued stable line or small step of lines into scrollback.

Data flow: It reads the queue inside StreamState, removes one animation step, increases the emitted-line counter by the number of lines released, and returns those released lines.

Call relations: The controller tick methods call this when the UI animation loop wants to move stable content from the queue into history.

Call graph: calls 1 internal fn (step); called by 2 (on_commit_tick, on_commit_tick).

fn tick_batch(&mut self, max_lines: usize) -> Vec<HyperlinkLine>

Purpose: Releases up to a requested number of queued stable lines at once. This is useful when the UI wants to drain faster than one animation step.

Data flow: It receives a maximum line count. If that count is zero, nothing changes. Otherwise it drains up to that many lines, updates the emitted count, and returns the drained lines.

Call relations: Both controller batch tick methods call this, then wrap any returned lines into display cells.

Call graph: calls 1 internal fn (drain_n); called by 2 (on_commit_tick_batch, on_commit_tick_batch); 1 external calls (new).

fn is_idle(&self) -> bool

Purpose: Reports whether the stable-line animation queue is empty. Callers use this to know whether there is more committed content waiting to be displayed.

Data flow: It reads StreamState’s queue status and returns a boolean. It does not change the stream.

Call relations: Controller tick methods call this after draining lines, so the outer streaming code can decide whether to keep ticking.

Call graph: calls 1 internal fn (is_idle); called by 4 (on_commit_tick, on_commit_tick_batch, on_commit_tick, on_commit_tick_batch).

fn queued_lines(&self) -> usize

Purpose: Returns how many stable lines are waiting in the animation queue. This is a simple visibility check for scheduling and tests.

Data flow: It reads the queue length from StreamState and returns that number. Nothing is modified.

Call relations: The public controllers expose this through their own queued_lines methods.

Call graph: calls 1 internal fn (queued_len); called by 2 (queued_lines, queued_lines).

fn oldest_queued_age(&self, now: Instant) -> Option<Duration>

Purpose: Tells how long the oldest queued stable line has been waiting. This can help the UI decide whether output is lagging.

Data flow: It receives the current time, asks StreamState about the oldest queued item, and returns an optional duration. If the queue is empty, there is no age.

Call relations: Both controller types expose this to higher-level streaming code.

Call graph: calls 1 internal fn (oldest_queued_age); called by 2 (oldest_queued_age, oldest_queued_age).

fn current_tail_lines(&self) -> Vec<HyperlinkLine>

Purpose: Returns the mutable live tail: rendered lines that are not yet safe to commit. This prevents queued-but-not-yet-emitted lines from appearing twice.

Data flow: It reads rendered_lines and starts at enqueued_stable_len, not emitted_stable_len. It copies and returns everything from that boundary to the end.

Call relations: Both controllers use this to show the active-cell tail while stable lines continue draining into scrollback.

Call graph: called by 2 (current_tail_lines, current_tail_lines).

fn has_tail(&self) -> bool

Purpose: Reports whether there is currently any mutable live tail. A live tail means part of the rendered output is still being held back from the stable queue.

Data flow: It compares the stable enqueue boundary with the total rendered-line count and returns true if rendered content remains beyond that boundary.

Call relations: Controllers expose this as has_live_tail, and width/render-mode changes use it to preserve tail content correctly.

Call graph: called by 4 (has_live_tail, has_live_tail, set_render_mode, set_width).

fn set_width(&mut self, width: Option<usize>)

Purpose: Updates the markdown render width after a terminal resize and rebuilds pending stable output for the new layout. This avoids replaying old lines or losing pending ones when wrapping changes.

Data flow: It receives a new optional width. If the width changed, it updates collector/render width, re-renders source, adjusts emitted counts to fit the new line count, clears stale queued lines, and rebuilds the queue when needed. It changes internal render and queue state but returns nothing.

Call relations: Both controllers call this from their set_width methods when the terminal changes size. It uses the same stable-boundary logic as normal streaming.

Call graph: calls 5 internal fn (clear_queue, queued_len, has_tail, rebuild_stable_queue_from_render, recompute_streaming_render); called by 2 (set_width, set_width).

fn reset(&mut self)

Purpose: Clears all state for the finished stream. This prevents text from one answer or plan leaking into the next one.

Data flow: It clears StreamState, raw source, rendered lines, counters, cache, and the table scanner. Afterward the core is empty but still reusable.

Call relations: Both finalize methods call this after they have taken the final source and output lines.

Call graph: calls 2 internal fn (clear, reset); called by 2 (finalize, finalize).

fn render_source(&self, source: &str) -> Vec<HyperlinkLine>

Purpose: Turns markdown source into terminal lines, either richly formatted or raw. It is the single place where the stream chooses how source text becomes visible output.

Data flow: It receives source text. In rich mode it renders markdown with links and current-directory-aware file display; in raw mode it turns source lines into plain hyperlink-line wrappers. It returns rendered HyperlinkLine values.

Call relations: Final rendering and every streaming re-render go through this helper.

Call graph: calls 3 internal fn (raw_lines_from_source, render_markdown_agent_with_links_and_cwd, plain_hyperlink_lines); called by 2 (finalize_remaining, recompute_streaming_render); 1 external calls (as_path).

fn recompute_streaming_render(&mut self)

Purpose: Refreshes the full rendered snapshot from the accumulated raw source. It keeps the visual model in sync after new complete source arrives or display settings change.

Data flow: It reads raw_source and current render settings, renders the source, and replaces rendered_lines with the new snapshot.

Call relations: push_delta, set_width, and set_render_mode call this before recalculating what can be stable.

Call graph: calls 1 internal fn (render_source); called by 3 (push_delta, set_render_mode, set_width).

fn set_render_mode(&mut self, render_mode: HistoryRenderMode)

Purpose: Switches between rich markdown rendering and raw text rendering while a stream may be active. It rebuilds pending output so the queue matches the new display style.

Data flow: It receives a render mode. If different, it records queue/tail state, changes mode, re-renders source, adjusts emitted counts, clears stale queue entries, and rebuilds stable lines when needed.

Call relations: Both controllers expose this for app-level display-mode changes. It follows almost the same repair path as set_width.

Call graph: calls 5 internal fn (clear_queue, queued_len, has_tail, rebuild_stable_queue_from_render, recompute_streaming_render); called by 2 (set_render_mode, set_render_mode).

fn compute_target_stable_len(&mut self) -> usize

Purpose: Calculates how many rendered lines are safe to move into the stable region. It is the main boundary decision between scrollback and live tail.

Data flow: It asks how many lines must be held as tail, subtracts that from the rendered-line count, and never lets the stable target move before already emitted lines. It returns the target stable length.

Call relations: Queue syncing and queue rebuilding both call this before deciding which lines to enqueue.

Call graph: calls 1 internal fn (active_tail_budget_lines); called by 2 (rebuild_stable_queue_from_render, sync_stable_queue).

fn sync_stable_queue(&mut self) -> bool

Purpose: Moves newly safe rendered lines into the animation queue. It also repairs the queue if a structural markdown change moves the safe boundary backward.

Data flow: It computes the target stable length, compares it with the current enqueued length, clears and rebuilds if needed, or appends only the newly stable slice. It returns true if the queue ended up with new work.

Call relations: push_delta calls this after re-rendering committed source, so incoming stream text can become animated scrollback.

Call graph: calls 4 internal fn (clear_queue, enqueue, queued_len, compute_target_stable_len); called by 1 (push_delta).

fn rebuild_stable_queue_from_render(&mut self)

Purpose: Recreates the stable queue from the current rendered snapshot. This is used when old queued lines can no longer be trusted, such as after resize or render-mode change.

Data flow: It computes the target stable boundary, clears the queue, enqueues the slice between already emitted lines and the target, and updates enqueued_stable_len.

Call relations: set_width and set_render_mode call this after they re-render the stream.

Call graph: calls 3 internal fn (clear_queue, enqueue, compute_target_stable_len); called by 2 (set_render_mode, set_width).

fn active_tail_budget_lines(&mut self) -> usize

Purpose: Decides how many rendered lines must stay mutable because of table holdback. In raw mode it disables this behavior because raw text does not reflow markdown tables.

Data flow: It reads the table scanner state. If a table is confirmed or a possible header is pending, it converts the source offset of that table/header into a rendered-line tail size; otherwise it returns zero.

Call relations: compute_target_stable_len calls this whenever the stable boundary is recalculated.

Call graph: calls 2 internal fn (tail_budget_from_source_start, state); called by 1 (compute_target_stable_len); 2 external calls (now, trace!).

fn tail_budget_from_source_start(&mut self, source_start: usize) -> usize

Purpose: Converts a table start position in raw source bytes into a count of rendered lines to hold back. This bridges source-text coordinates and terminal-line coordinates.

Data flow: It receives a source byte offset. If the table starts at the beginning, all rendered lines are tail; otherwise it renders or retrieves the prefix length before that offset and subtracts it from the full rendered length.

Call relations: active_tail_budget_lines calls this after the table scanner identifies where the mutable table region begins.

Call graph: calls 1 internal fn (stable_prefix_len_for_source_start); called by 1 (active_tail_budget_lines).

fn stable_prefix_len_for_source_start(&mut self, source_start: usize) -> usize

Purpose: Finds how many rendered lines exist before a table starts. It caches the answer because table streams can ask the same question repeatedly.

Data flow: It receives a source byte offset, checks whether a cached answer matches that offset and width, and otherwise renders only the source prefix to count its lines. It stores and returns the count.

Call relations: tail_budget_from_source_start uses this to compute how much of the current render can remain stable before a table.

Call graph: calls 1 internal fn (render_markdown_agent_with_links_and_cwd); called by 1 (tail_budget_from_source_start); 3 external calls (now, as_path, trace!).

fn new(width: Option<usize>, cwd: &Path, render_mode: HistoryRenderMode) -> Self

Purpose: Creates a controller for streaming a normal agent message. It adds agent-message behavior on top of the shared StreamCore.

Data flow: It receives width, current directory, and render mode, builds a StreamCore, and starts with no header emitted. It returns a StreamController.

Call relations: Higher-level answer streaming code creates this when an agent response starts.

Call graph: calls 1 internal fn (new); called by 4 (handle_streaming_delta, flush_answer_stream_keeps_default_reflow_for_plain_text_tail, flush_answer_stream_requests_scrollback_reflow_for_live_table_tail, stream_controller).

fn push(&mut self, delta: &str) -> bool

Purpose: Adds a new text delta to an agent-message stream. It returns whether new stable lines became available.

Data flow: It passes the delta into StreamCore::push_delta and returns that result unchanged.

Call relations: This is the agent-message wrapper around the shared push path.

Call graph: calls 1 internal fn (push_delta).

fn finalize(&mut self) -> (Option<Box<dyn HistoryCell>>, Option<String>)

Purpose: Finishes an agent-message stream and returns both the final display cell and the raw markdown source. The source is used later to consolidate the transcript.

Data flow: It asks the core for remaining rendered lines. If there is no source, it resets and returns nothing; otherwise it takes the raw source, emits the remaining lines as an agent cell, resets the core, and returns the cell plus source.

Call relations: Called when an agent answer ends. It hands final lines to emit and then clears state for the next stream.

Call graph: calls 3 internal fn (emit, finalize_remaining, reset); 1 external calls (take).

fn on_commit_tick(&mut self) -> (Option<Box<dyn HistoryCell>>, bool)

Purpose: Releases the next queued stable part of an agent message. It also reports whether the stable queue is now idle.

Data flow: It ticks the core, wraps any returned lines into an agent message cell, checks idle status, and returns both values.

Call relations: The stream-draining code calls this during animation ticks.

Call graph: calls 3 internal fn (emit, is_idle, tick); called by 1 (drain_stream_controller).

fn on_commit_tick_batch(
        &mut self,
        max_lines: usize,
    ) -> (Option<Box<dyn HistoryCell>>, bool)

Purpose: Releases several queued stable agent-message lines at once. This is the faster-drain version of on_commit_tick.

Data flow: It receives a maximum line count, asks the core to drain up to that many lines, emits them as an agent cell if present, and returns the cell plus idle status.

Call relations: The stream-draining code calls this when batching is allowed.

Call graph: calls 3 internal fn (emit, is_idle, tick_batch); called by 1 (drain_stream_controller).

fn queued_lines(&self) -> usize

Purpose: Reports how many agent-message lines are queued for stable commit.

Data flow: It reads the count through StreamCore and returns it.

Call relations: Higher-level scheduling and tests use this to inspect backlog.

Call graph: calls 1 internal fn (queued_lines).

fn oldest_queued_age(&self, now: Instant) -> Option<Duration>

Purpose: Reports how long the oldest queued agent-message line has been waiting.

Data flow: It receives the current time, forwards it to StreamCore, and returns the optional duration.

Call relations: This lets outer code detect or react to slow-draining output.

Call graph: calls 1 internal fn (oldest_queued_age).

fn current_tail_lines(&self) -> Vec<HyperlinkLine>

Purpose: Returns the current live tail for a normal agent message.

Data flow: It asks StreamCore for rendered lines beyond the stable enqueue boundary and returns them.

Call relations: The UI uses this when drawing the active streaming cell.

Call graph: calls 1 internal fn (current_tail_lines).

fn tail_starts_stream(&self) -> bool

Purpose: Tells whether the live tail begins at the very start of the agent message. This helps decide whether the message header should appear with the tail.

Data flow: It checks whether no header has been emitted and no stable lines have been enqueued. It returns a boolean.

Call relations: Display code can use this when presenting a tail before any committed cell exists.

fn has_live_tail(&self) -> bool

Purpose: Reports whether an agent message currently has mutable tail content.

Data flow: It delegates to StreamCore::has_tail and returns the result.

Call relations: Outer streaming logic uses this to know whether active-cell content must still be drawn or reflowed.

Call graph: calls 1 internal fn (has_tail).

fn clear_queue(&mut self)

Purpose: Drops pending stable agent-message lines from the animation queue and aligns the enqueue boundary with already emitted content.

Data flow: It clears StreamState’s queue and sets enqueued_stable_len to emitted_stable_len. Existing raw source and rendered tail remain.

Call relations: Higher-level code can call this when it intentionally abandons queued animation work.

fn set_width(&mut self, width: Option<usize>)

Purpose: Updates the render width for an active agent-message stream.

Data flow: It receives a new width and forwards it to StreamCore::set_width, which re-renders and repairs the queue.

Call relations: Called by UI resize handling for ordinary answer streams.

Call graph: calls 1 internal fn (set_width).

fn set_render_mode(&mut self, render_mode: HistoryRenderMode)

Purpose: Changes how an active agent-message stream is rendered, such as rich markdown versus raw text.

Data flow: It receives the new mode and forwards it to StreamCore::set_render_mode.

Call relations: Called when app display settings change while an answer is streaming.

Call graph: calls 1 internal fn (set_render_mode).

fn emit(&mut self, lines: Vec<HyperlinkLine>) -> Option<Box<dyn HistoryCell>>

Purpose: Wraps rendered agent-message lines into a history cell, adding the message header only once.

Data flow: It receives hyperlink-aware lines. If empty, it returns nothing; otherwise it creates an AgentMessageCell and flips header_emitted so later chunks are continuations.

Call relations: Finalize and both commit-tick methods call this after the core provides lines to display.

Call graph: calls 1 internal fn (new_hyperlink_lines); called by 3 (finalize, on_commit_tick, on_commit_tick_batch); 1 external calls (new).

fn new(width: Option<usize>, cwd: &Path, render_mode: HistoryRenderMode) -> Self

Purpose: Creates a controller for streaming a proposed plan block. It uses the shared streaming core but tracks plan-specific header and padding state.

Data flow: It receives width, current directory, and render mode, builds a StreamCore, and initializes header and padding flags to false. It returns a PlanStreamController.

Call relations: Plan delta handling creates this when a proposed plan begins streaming.

Call graph: calls 1 internal fn (new); called by 5 (on_plan_delta, completed_token_activity_refresh_retries_after_plan_item_completion, completed_plan_table_tail_skips_provisional_history_insert, finalized_plan_stream_preserves_semantic_url_fragments, plan_stream_controller).

fn push(&mut self, delta: &str) -> bool

Purpose: Adds a new text delta to a proposed-plan stream. It returns whether new stable plan lines were queued.

Data flow: It forwards the delta to StreamCore::push_delta and returns the boolean result.

Call relations: This is the plan-stream wrapper around the shared push logic.

Call graph: calls 1 internal fn (push_delta).

fn finalize(&mut self) -> (Option<Box<dyn HistoryCell>>, Option<String>)

Purpose: Finishes a proposed-plan stream and returns the final styled cell plus raw markdown source. It includes bottom padding in the final plan block.

Data flow: It asks the core for remaining lines, exits with nothing if there is no source, otherwise takes the raw source, emits remaining lines with bottom padding, resets the core, and returns the cell plus source.

Call relations: Called when plan streaming ends, before transcript consolidation.

Call graph: calls 3 internal fn (emit, finalize_remaining, reset); 1 external calls (take).

fn on_commit_tick(&mut self) -> (Option<Box<dyn HistoryCell>>, bool)

Purpose: Releases the next queued stable part of a proposed plan. It keeps final-only padding out of intermediate chunks.

Data flow: It ticks the core, emits returned lines as a plan cell without bottom padding, checks whether the core is idle, and returns both values.

Call relations: Plan stream draining calls this during animation ticks.

Call graph: calls 3 internal fn (emit, is_idle, tick); called by 1 (drain_plan_stream_controller).

fn on_commit_tick_batch(
        &mut self,
        max_lines: usize,
    ) -> (Option<Box<dyn HistoryCell>>, bool)

Purpose: Releases several queued stable proposed-plan lines at once. It is the batched version of the plan commit tick.

Data flow: It receives a maximum line count, drains up to that many lines from the core, emits them without bottom padding, and returns the optional cell plus idle status.

Call relations: Plan stream draining calls this when it wants to catch up more quickly.

Call graph: calls 3 internal fn (emit, is_idle, tick_batch); called by 1 (drain_plan_stream_controller).

fn queued_lines(&self) -> usize

Purpose: Reports how many proposed-plan lines are waiting to be committed.

Data flow: It asks StreamCore for its queue length and returns that number.

Call relations: Used by higher-level plan streaming code and tests to inspect pending output.

Call graph: calls 1 internal fn (queued_lines).

fn has_live_tail(&self) -> bool

Purpose: Reports whether the proposed plan has mutable live-tail content.

Data flow: It delegates to StreamCore::has_tail and returns the result.

Call relations: The UI uses this to know whether to draw provisional plan content.

Call graph: calls 1 internal fn (has_tail).

fn current_tail_lines(&self) -> Vec<HyperlinkLine>

Purpose: Returns the raw rendered live-tail lines for a proposed plan, before plan-specific decoration.

Data flow: It asks StreamCore for the tail slice beyond the stable boundary and returns it.

Call relations: current_tail_display_lines builds on this to produce styled plan-tail display lines.

Call graph: calls 1 internal fn (current_tail_lines); called by 1 (current_tail_display_lines).

fn tail_starts_stream(&self) -> bool

Purpose: Tells whether the proposed plan’s live tail begins before any plan header has been emitted.

Data flow: It checks the header flag and the core’s stable enqueue boundary. It returns true only when the stream is still at its first visible content.

Call relations: Display code can use this to decide whether the live plan tail should include the plan header.

fn current_tail_display_lines(&self) -> Vec<HyperlinkLine>

Purpose: Returns the current proposed-plan live tail with plan styling applied. This is what the active plan tail should look like on screen.

Data flow: It gets raw tail lines. If there are none, it returns an empty list; otherwise it runs them through render_display_lines without final bottom padding.

Call relations: It connects the shared core tail with the plan-specific formatting helper.

Call graph: calls 2 internal fn (current_tail_lines, render_display_lines); 1 external calls (new).

fn oldest_queued_age(&self, now: Instant) -> Option<Duration>

Purpose: Reports how long the oldest queued proposed-plan line has been waiting.

Data flow: It forwards the current time to StreamCore and returns the optional age.

Call relations: Outer plan streaming code can use this for pacing or catch-up decisions.

Call graph: calls 1 internal fn (oldest_queued_age).

fn clear_queue(&mut self)

Purpose: Clears pending stable plan lines and resets the stable boundary to already emitted content.

Data flow: It clears the core queue and sets enqueued_stable_len equal to emitted_stable_len. It leaves source and current render data intact.

Call relations: Higher-level code can call this when it wants to discard queued plan animation work.

fn set_width(&mut self, width: Option<usize>)

Purpose: Updates the render width for an active proposed-plan stream.

Data flow: It receives the new width and delegates to StreamCore::set_width, which re-renders and rebuilds pending output.

Call relations: Called during terminal resize handling for plan streams.

Call graph: calls 1 internal fn (set_width).

fn set_render_mode(&mut self, render_mode: HistoryRenderMode)

Purpose: Changes the render mode for an active proposed-plan stream.

Data flow: It receives the new mode and delegates to StreamCore::set_render_mode.

Call relations: Called when display mode changes while plan content is streaming.

Call graph: calls 1 internal fn (set_render_mode).

fn emit(
        &mut self,
        lines: Vec<HyperlinkLine>,
        include_bottom_padding: bool,
    ) -> Option<Box<dyn HistoryCell>>

Purpose: Wraps proposed-plan lines into a styled plan history cell. It controls whether the chunk is the first plan block or a continuation.

Data flow: It receives lines and a bottom-padding flag. If there is no content and no padding needed, it returns nothing; otherwise it formats display lines, marks header and top padding as emitted, and returns a proposed-plan stream cell.

Call relations: Plan finalize and plan commit ticks call this after the core produces lines.

Call graph: calls 1 internal fn (render_display_lines); called by 3 (finalize, on_commit_tick, on_commit_tick_batch); 2 external calls (new, new_proposed_plan_stream).

fn render_display_lines(
        &self,
        lines: Vec<HyperlinkLine>,
        include_bottom_padding: bool,
    ) -> Vec<HyperlinkLine>

Purpose: Applies the proposed-plan visual shape: title, spacing, indentation, and background style. It turns plain rendered markdown lines into plan-block display lines.

Data flow: It receives plan content lines and a bottom-padding flag. It may add the “Proposed Plan” header, top padding, bottom padding, prefixes each plan line with spaces, applies the plan style, and returns the decorated lines.

Call relations: Plan emit uses this for committed cells, and current_tail_display_lines uses it for live tails.

Call graph: calls 3 internal fn (proposed_plan_style, new, prefix_hyperlink_lines); called by 2 (current_tail_display_lines, emit); 3 external calls (from, with_capacity, vec!).

fn test_cwd() -> PathBuf

Purpose: Provides a stable current-directory path for tests without depending on a particular operating-system root.

Data flow: It reads the system temporary directory and returns it as a PathBuf.

Call relations: The test controller factory helpers call this when constructing stream controllers.

Call graph: 1 external calls (temp_dir).

fn stream_controller(width: Option<usize>) -> StreamController

Purpose: Creates a rich-rendering agent StreamController for tests.

Data flow: It receives an optional width, gets the test current directory, and returns a StreamController in rich render mode.

Call relations: Most agent-stream tests use this helper to avoid repeated setup.

Call graph: calls 1 internal fn (new); 1 external calls (test_cwd).

fn plan_stream_controller(width: Option<usize>) -> PlanStreamController

Purpose: Creates a rich-rendering PlanStreamController for tests.

Data flow: It receives an optional width, gets the test current directory, and returns a plan controller in rich render mode.

Call relations: Plan-stream tests use this helper for consistent setup.

Call graph: calls 1 internal fn (new); 1 external calls (test_cwd).

fn lines_to_plain_strings(lines: &[ratatui::text::Line<'_>]) -> Vec<String>

Purpose: Converts styled terminal lines into plain strings for easy assertions.

Data flow: It receives ratatui Line values, joins the text content of their spans, and returns one plain string per line.

Call relations: Many tests use this to compare visible output without caring about style objects.

Call graph: 1 external calls (iter).

fn hyperlink_lines_to_plain_strings(lines: &[HyperlinkLine]) -> Vec<String>

Purpose: Converts hyperlink-aware lines into plain strings for assertions.

Data flow: It receives HyperlinkLine values, extracts their visible terminal lines, and passes them through lines_to_plain_strings.

Call relations: Tail-related tests use this when checking live hyperlink-line output.

Call graph: calls 1 internal fn (visible_lines); 2 external calls (lines_to_plain_strings, to_vec).

fn collect_streamed_lines(deltas: &[&str], width: Option<usize>) -> Vec<String>

Purpose: Runs a full agent-message streaming scenario and collects the final plain transcript lines.

Data flow: It receives deltas and a width, pushes each delta through a StreamController, drains commit ticks after each push, finalizes, strips the agent bullet prefix, and returns plain strings.

Call relations: Many table and markdown tests use this helper to compare streamed output with full rendering.

Call graph: 3 external calls (new, lines_to_plain_strings, stream_controller).

fn collect_plan_streamed_lines(deltas: &[&str], width: Option<usize>) -> Vec<String>

Purpose: Runs a full proposed-plan streaming scenario and collects plain transcript lines.

Data flow: It receives deltas and a width, pushes them through a PlanStreamController, drains ticks, finalizes, and returns plain strings.

Call relations: Plan-specific tests use this to compare streamed and baseline plan output.

Call graph: 3 external calls (new, lines_to_plain_strings, plan_stream_controller).

fn controller_set_width_rebuilds_queued_lines()

Purpose: Checks that resizing rebuilds queued agent lines using the new width.

Data flow: It streams a long line at a wide width, resizes narrower, drains the queue, and asserts that the rendered output now wraps across multiple lines.

Call relations: This protects StreamCore::set_width and queue rebuilding behavior.

Call graph: 4 external calls (assert!, assert_eq!, lines_to_plain_strings, stream_controller).

fn controller_set_width_no_duplicate_after_emit()

Purpose: Ensures already emitted content is not re-queued after a resize.

Data flow: It streams and fully emits a line, resizes, then checks that the queue remains empty.

Call relations: This guards the resize path that skips replay when there is no pending queue or live tail.

Call graph: 3 external calls (assert!, assert_eq!, stream_controller).

fn controller_tick_batch_zero_is_noop()

Purpose: Verifies that asking to drain zero lines changes nothing.

Data flow: It queues one line, calls the batch tick with max_lines zero, and asserts no cell is emitted, the stream is not idle, and the queue length stays one.

Call relations: This protects StreamCore::tick_batch’s zero-count early return.

Call graph: 3 external calls (assert!, assert_eq!, stream_controller).

fn controller_has_live_tail_reflects_tail_presence()

Purpose: Checks that the agent controller reports live-tail presence based on the stable boundary.

Data flow: It manually inserts a rendered tail line, toggles the enqueue boundary, and asserts has_live_tail changes accordingly.

Call relations: This directly exercises StreamController::has_live_tail through StreamCore::has_tail.

Call graph: 3 external calls (assert!, stream_controller, vec!).

fn plan_controller_has_live_tail_reflects_tail_presence()

Purpose: Checks that the plan controller reports live-tail presence correctly.

Data flow: It manually inserts a rendered line and moves the enqueue boundary before and after it, asserting the live-tail flag follows.

Call relations: This mirrors the agent live-tail test for PlanStreamController.

Call graph: 3 external calls (assert!, plan_stream_controller, vec!).

fn controller_live_tail_keeps_uncommitted_table_cell_newline_gated()

Purpose: Ensures an unfinished table row does not appear in the live tail before its newline arrives.

Data flow: It streams a table header, delimiter, and a partial row without newline, then checks the visible tail does not contain the partial text.

Call relations: This protects push_delta’s complete-line commit rule for table safety.

Call graph: 3 external calls (assert!, hyperlink_lines_to_plain_strings, stream_controller).

fn controller_live_tail_requires_table_holdback_state()

Purpose: Ensures ordinary partial text is not shown as a live tail unless holdback rules require it.

Data flow: It streams plain text without a newline and asserts current tail lines are empty and no live tail exists.

Call relations: This guards against showing uncommitted non-table fragments.

Call graph: 2 external calls (assert!, stream_controller).

fn controller_live_tail_rerenders_table_tail_after_resize()

Purpose: Checks that a live table tail is re-rendered each time the width changes.

Data flow: It streams a table, resizes to several widths, compares the current tail with a fresh markdown render at each width, and expects equality.

Call relations: This tests the interaction of table holdback, current_tail_lines, and set_width.

Call graph: calls 1 internal fn (append_markdown_agent); 5 external calls (new, assert_eq!, hyperlink_lines_to_plain_strings, lines_to_plain_strings, stream_controller).

fn controller_set_width_partial_drain_no_lost_lines()

Purpose: Ensures resizing after only part of the queue has drained does not lose later lines.

Data flow: It streams two lines, emits one tick, resizes, finalizes, and checks that the second line is still present.

Call relations: This protects the resize repair logic for partially drained queues.

Call graph: 2 external calls (assert!, stream_controller).

fn controller_set_width_partial_drain_keeps_pending_queue()

Purpose: Checks that pending queued lines remain available after a resize during partial drain.

Data flow: It streams wrapped content, emits one tick, resizes, confirms the queue still has work, drains it, and verifies the later line appears.

Call relations: This exercises set_width followed by normal commit ticks.

Call graph: 4 external calls (new, assert!, lines_to_plain_strings, stream_controller).

fn controller_set_width_preserves_in_flight_tail()

Purpose: Ensures a partial agent-message tail survives a resize before finalization.

Data flow: It streams text without a newline, resizes, finalizes, and checks the final cell contains that text.

Call relations: This protects resize handling when the collector has in-flight source.

Call graph: 3 external calls (assert_eq!, lines_to_plain_strings, stream_controller).

fn controller_set_width_preserves_table_tail_when_queue_is_empty()

Purpose: Checks that a held table header remains as live tail across resize even when no stable queue exists.

Data flow: It emits an intro line, starts a table header, resizes, and verifies the table header still appears in the tail.

Call relations: This protects set_width’s special handling for live tails without pending queue lines.

Call graph: 4 external calls (assert!, assert_eq!, hyperlink_lines_to_plain_strings, stream_controller).