Function overlay_with 

pub fn overlay_with<R: Resolve>(
    page: &mut Page,
    page_dict: &Dict,
    catalog: &Dict,
    r: &R,
    ctx: &mut BuildContext,
    limits: &Limits,
    diags: &mut Diagnostics,
    supplied: Option<&AnnotOverlay>,
)

The same pass, with an overlay the caller has already filled in.

supplied is laid over what this function generates, per ap::AnnotOverlay::merge_over: wherever it has something to say about an annotation the caller’s entry wins, and wherever it is untouched the generated one stands. Passing None is exactly overlay, down to the operators emitted.

This is how a live edit reaches the page. A form session holds appearances for the fields it has touched — a focused field with a caret, a committed value, or a field whose appearance it has cleared — and hands them here rather than having them regenerated from the document, which would not know about the edit.

Keying

Both overlays are keyed by the raw /Annots index — the index into the array as the file writes it, which is what AnnotList::source_indices recovers after the list has dropped and reordered entries. A caller building supplied must use that index and not the position an annotation ended up at in the loaded list.

Focus

supplied may also name the annotation that holds the keyboard focus, through ap::AnnotOverlay::set_focus. That annotation is drawn without the widget tint and with focus_rect’s dashed outline over whatever focus box it declares — see focus_rect for why the two travel together and why most field types declare none.