@spec create_segment_request(:header | :footer, non_neg_integer()) :: map()

createHeader/createFooter request for a fresh DEFAULT segment on the section whose section break sits at break_index — the section break element's own startIndex (NOT the insertSectionBreak request's location.index, one less — see append_template/3's doc on why the break inserts a newline ahead of itself).

@spec extra_paragraph_style_requests(integer(), [{map(), map()}]) :: [map()]

updateParagraphStyle requests for fields GoogleDocsClient.paragraph_style_requests/2 deliberately doesn't capture (borders, shading) — a header/footer replay's own pass, kept separate from the shared, narrow body builder (which is covered by exact batch-content tests body appends rely on) rather than widening it. One request per span that has at least one such field; a span with none gets none — no anti-inheritance mask needed here, since every field is on a brand new, isolated segment with nothing adjacent to inherit from.

spans_with_extras — [{span, extras}], span shaped like GoogleDocsClient.paragraph_style_requests/2's (start_offset, length), extras a map with border_top/border_bottom/ border_left/border_right (each the source's own raw Docs Border object, or nil), shading (raw Shading object or nil), and space_below (a bare point value or nil — the horizontalRule stand-in's forced 6pt gap, see paragraph_extras/1's caller).

@spec extra_text_style_requests(integer(), [{map(), map()}]) :: [map()]

updateTextStyle requests for fields GoogleDocsClient.text_style_requests/2 deliberately doesn't capture (weightedFontFamily, underline, link, baselineOffset), same separate-pass reasoning as extra_paragraph_style_requests/2.

runs_with_extras — [{run, extras}], run shaped like GoogleDocsClient.text_style_requests/2's (start_offset, length), extras a map with weighted_font_family/underline/link/ baseline_offset (each the source's own raw value, or nil) and font_size (a bare point value, or nil — the horizontalRule stand-in's forced 4pt, see text_extras/1's caller; NOT the same as the shared builder's own captured font_size, which this leaves alone unless a rule forces an override).

@spec fingerprint([map()], map()) :: term()

Structural fingerprint of a header/footer segment's content (or a table cell's content — same shape), for comparing "does this look like the same header/footer" across documents. Two segments fingerprint equal iff == on the returned term holds. See the moduledoc for what's kept/dropped and why.

@spec replayable?([map()], map()) :: boolean()

Whether a header/footer segment's content can be rebuilt faithfully by the replay. The replay rebuilds text runs, rule paragraphs, and one-row- or-more tables whose cells hold text or a single inline image. Anything else would be dropped silently or rejected by the API:

• autoText (page numbers / page counts) — the Docs API cannot insert it, so a replayed "Page 1 of 3" footer would come out "Page of ".
• an inline image outside a table cell, a cell with more than one image or an image next to text, or an image with no contentUri (drawings, charts) — only an image-only cell's single picture is re-inserted.
• positioned (floating) objects, nested tables, and any other element kind (equations, footnote references, …).

false keeps the section on the header/footer it inherits instead of replacing it with a lossy copy.

@spec segment_id_from_replies(:header | :footer, [map()]) :: String.t() | nil

Pulls the new segment's id out of a createHeader/createFooter batch response's replies.

@spec skeleton_requests(String.t(), [map()], [map()]) :: [map()]

Phase (б) of the replay: insert the flattened text (table markers included, see GoogleDocsClient.flatten_template_with_table_markers_and_styles/1) at the start of a fresh (empty) segment, then its paragraph and text style. text already has its own final trailing newline stripped by the caller when the template ends in a plain paragraph (the Docs API refuses to delete a segment's terminal newline, so the segment's own pre-existing one serves as that paragraph's terminator instead — see GoogleDocsClient.skeleton_insert_text/2's doc); an empty text (a template that's a single, otherwise-empty paragraph) skips insertText entirely — the API rejects an empty one, same as body's/a cell's, and the paragraph/text style requests below still apply, targeting the segment's own pre-existing newline. No segmentId yet — wrap the result with with_segment_id/2.

@spec table_fill_requests([map()], map()) :: [map()]

Phase (в) of the replay: column widths, cell style (padding/alignment replayed, borders always cleared — a bare insertTable cell renders with a visible border every captured home table lacks), cell text/style, and inline images (verbatim source size and URI — see the moduledoc).

entries — one map per table, built by the caller from a re-fetched document (GoogleDocsClient.extract_table_cells/1's cells matched against the captured template table): %{table_start, columns, cells, column_properties, cell_styles, cell_texts, cell_runs, cell_paragraphs, cell_image_ids, cell_paragraph_extras, cell_run_extras}. All the cell_* lists are row-major and index-aligned with each other (same padding-to-column-count — see flatten_template_with_table_markers_and_styles/1's normalize_row/3). cell_image_ids entries are nil or an inlineObjects key. cell_paragraph_extras/cell_run_extras are themselves lists (one per cell, parallel to cell_paragraphs/cell_runs) of {span, extras} / {run, extras} pairs in extra_paragraph_style_requests/2's and extra_text_style_requests/2's own shape — a cell's border/font-family/ underline/link get the same separate-pass treatment as body content. columns is the table's column count; each row-major cell_styles entry is addressed at {div(i, columns), rem(i, columns)}, so a multi-row table's second row lands on row 1 rather than on an out-of-range column of row 0.

No segmentId yet — wrap the result with with_segment_id/2.

@spec with_segment_id([map()], String.t()) :: [map()]

Wraps already-built, segment-agnostic requests (from GoogleDocsClient.paragraph_style_requests/2, GoogleDocsClient.text_style_requests/2, GoogleDocsClient.paragraph_then_text_style_requests/3, GoogleDocsClient.table_column_width_requests/2, GoogleDocsClient.table_skeleton_requests/2, and this module's own builders) for a specific header/footer segment: every location, range, and tableStartLocation map found anywhere in the request tree gets segmentId merged in (existing keys win — nothing is overwritten). This is deliberately a transform over the result of those builders rather than a segment-aware copy of each one: the coordinate keys a Docs API request can carry are a small, closed set, so one generic walk covers every request shape above (and any new one built the same way) instead of duplicating each builder with a segment_id argument threaded through every range/location it emits.