Hit-testing by coordinate, selection, and document edits

Coordinate → document position

Coordinate units

The hit-test-docx command takes --x and --y in thousandths of a pixel. The value 100000 in the example below is 100 px, not one hundred thousand. :::

# $CLI — path to the processor, see "Installation and verification"
"$CLI" hit-test-docx /data/contract.docx \
  --x 100000 --y 100000 --format json

{
  "model_version": "fastdoc-d6-hit-test-snapshot-v2",
  "hit_test_mode": "body-line-boxes-line-edge-caret-only",
  "result_kind": "body-line-hit",
  "page_index": 0,
  "paragraph_index": 0,
  "paragraph_location": "word/document.xml:body.block[0]",
  "line_index": 0,
  "caret_slot_index": 1,
  "line_scene_x_milli_px": 96000,
  "line_scene_y_milli_px": 96000
}

What this call can and can’t do

The command responds along lines of the main text and returns the caret position within the line — that’s what body-line-boxes-line-edge-caret-only means in the hit_test_mode field. It doesn’t distinguish tables, text boxes, or graphic objects: a click on a table cell returns a position in the line, not the cell itself.

There is no hit-test command in a persistent session at all — this call is separate, one-off, and needs no open session.

The desktop app can do more: hit-testing into text and into a table cell. These modes aren’t exposed yet — before opening them up, we need to define which kinds of objects the embedding application is allowed to touch. :::

Simple point edit and save

The mutate command addresses a location by paragraph number and offset within it — hence “point edit”: the edit lands exactly at the named spot and goes no further. It checks nothing: if the document changed between the read and the edit, the edit lands at the old coordinates. It suits scenarios with a single session where nothing happens between the read and the write.

{"id":"edit-1","cmd":"mutate",
 "operation_kind":"insert-text","paragraph_index":0,
 "offset":7,"text":"SumDoc "}
{"id":"save-1","cmd":"save","path":"/data/contract-edited.docx"}

The preferred typed transaction

The apply-text-transaction command carries the request, document, session, and view identifiers, together with the expected document and selection revisions. The core checks them before applying the change: if the document or selection has moved on, the request is refused entirely, not applied halfway. That’s why this path is preferred for integration — see Typed edit types.

{
  "id": "tx-1", "cmd": "apply-text-transaction",
  "request": {
    "request_id": "req-8", "document_id": "contract-42",
    "session_id": "session-1", "view_id": "canvas-1",
    "expected_revision": 42, "expected_selection_revision": 17,
    "command": {"type":"insert_text",
      "at":{"story_id":"body",
            "node_id":"paragraph:body.block[0]",
            "utf16_offset":7,"affinity":"downstream"},
      "text":"SumDoc "}
  }
}