[SPARK-55300][DOCS] Add timestamp offset option visualization in Kafka docs

### What changes were proposed in this pull request?

Adds a diagram illustrating the behavior the the timestamp offset options for Kafka.

### Why are the changes needed?

The text explanation of the timestamp offset options in the guide doc was not sufficient for many users to form the above illustration in their minds. Their feedback is something like “A picture is worth a thousand words”.

### Does this PR introduce _any_ user-facing change?

No. Documentation updates only.

### How was this patch tested?

N/A. Verified that the docs build as expected.

<img width="595" height="526" alt="Screenshot 2026-01-30 at 4 24 13 PM" src="https://github.com/user-attachments/assets/dfad6db0-22f1-45dd-b4ea-a2b2592402ee" />

[site.zip](https://github.com/user-attachments/files/24975955/site.zip)
- See `/streaming/structured-streaming-kafka-integration.html`

### Was this patch authored or co-authored using generative AI tooling?

No. AI was only used for consultation purposes.

Closes #54080 from kavpreetgrewal/update-kafka-offset-doc.

Authored-by: Kavpreet Grewal <kavpreet.grewal@databricks.com>
Signed-off-by: Jungtaek Lim <kabhwan.opensource@gmail.com>

Author: kavpreetgrewal

docs/streaming/structured-streaming-kafka-integration.md

@@ -587,6 +587,46 @@ Also, the meaning of <code>timestamp</code> here can be vary according to Kafka
 
 Timestamp offset options require Kafka 0.10.1.0 or higher.
 
+#### Timestamp offset behavior illustrated
+
+The following diagrams illustrate how Kafka resolves offsets when querying by timestamp for any particular topic partition. Each diagram shows a timeline with records (r1, r2, r3, ...) and the provided timestamp (ts), which can be global or per partition. The returned offset points to the **first record whose timestamp is greater than or equal to the provided timestamp**.
+
+**Scenario 1: Timestamp is before existing records**
+
+```
+Timeline:  ───────|────────|───|───|───|───|──▶
+                  ts       r1  r2  r3  r4  r5
+                           ↑
+                        returned
+
+Result: r1 is returned (first record with timestamp >= ts)
+```
+
+**Scenario 2: Timestamp is after all existing records**
+
+```
+Timeline:  ──|───|───|───|───|─────────────|──▶
+             r1  r2  r3  r4  r5            ts
+                                           ↑
+                                     no match found
+
+Result: No offset returned by Kafka; behavior falls back to
+        startingOffsetsByTimestampStrategy ("error" or "latest")
+```
+
+**Scenario 3: Timestamp falls between records**
+
+```
+Timeline:  ─────|─────────|──────|──────────|──▶
+                r1        ts     r2         r3
+                                 ↑
+                              returned
+
+Result: r2 is returned (first record with timestamp >= ts)
+```
+
+**Note:** For starting offsets, ingestion begins from the returned offset (inclusive), or follows <code>startingOffsetsByTimestampStrategy</code> in scenario 2. For ending offsets, ingestion stops at the returned offset (exclusive), or falls back to latest in scenario 2.
+
 ### Offset fetching
 
 In Spark 3.0 and before Spark uses <code>KafkaConsumer</code> for offset fetching which could cause infinite wait in the driver.