Page tap-target queries: link + image hit-test, anchor lookup, href split. More...

#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "reflow.h"

Include dependency graph for reflow_link.c:

Functions
ra8_err_t	reflow_hit_test_link (const reflow_t engine, uint32_t page_idx, int32_t x, int32_t y, uint32_t out_href_off, uint32_t *out_href_len)
	Hit-test a point on a page against the laid-out <a> link rectangles.
ra8_err_t	reflow_hit_test_image (const reflow_t engine, uint32_t page_idx, int32_t x, int32_t y, uint32_t out_index)
	Hit-test a point on a page against the laid-out <img> boxes (#478).
ra8_err_t	reflow_find_anchor (const reflow_t engine, const char id, uint32_t id_len, uint32_t *out_page)
	Find the page of a same-chapter id anchor (for #fragment jumps).
static bool	internal_has_scheme (const char *href, uint32_t end)
	True iff `href` has a URI scheme (a ':' before any '/' in [0,end)).
static void	internal_href_classify (const char href, uint32_t len, reflow_href_kind_t out_kind, uint32_t out_path_len, uint32_t out_frag_off, uint32_t *out_frag_len)
	Core href split + classify (no validation; pure on the inputs).
ra8_err_t	reflow_href_split (const char href, uint32_t len, reflow_href_kind_t out_kind, uint32_t out_path_len, uint32_t out_frag_off, uint32_t *out_frag_len)
	Split + classify an <a href> into a path part and a #fragment.

Variables
static const char *const	s_tag_link = "ra8_link"
	Log tag for the link/anchor query module.

Detailed Description

Page tap-target queries: link + image hit-test, anchor lookup, href split.

Implements the public "what did the user tap on this page" query surface declared in reflow.h (#110, extended for tap-to-zoom in #478). The layout pass (reflow_layout.c) populates engine->link_rects[], engine->link_targets[], engine->anchors[] and engine->image_boxes[]; this TU reads them:

reflow_hit_test_link(): point -> href (for a tap).
reflow_hit_test_image(): point -> laid-out <img> box index.
reflow_find_anchor(): #fragment id -> page.
reflow_href_split(): pure classification of an href string.

[Ring 4 / Reflow] {World: NS}

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file reflow_link.c.

Function Documentation

◆ internal_has_scheme()

bool internal_has_scheme	(	const char *	href,
		uint32_t	end )

static

True iff href has a URI scheme (a ':' before any '/' in [0,end)).

A scheme makes the link external (http:, https:, mailto:, ...), which the e-reader does not follow. A ':' after a '/' is a path character, not a scheme. The function scans bytes in order from index 0 up to (but not including) end; the first '/' terminates the scan with a false result and the first ':' terminates it with a true result. If neither character appears within the range the link is treated as scheme-free.

Parameters

[in]	href	Href byte array; must not be NULL when end > 0.
[in]	end	Exclusive scan bound (the '#' position or total length).

Returns: bool Classification result.

Return values

true	A URI scheme delimiter ':' was found before any '/'.
false	No scheme present; ':' absent or appears after the first '/'.

Precondition: href is a valid pointer to at least end readable bytes.; end is less than or equal to the total length of the href buffer.

Postcondition: The href buffer is not modified.; The return value reflects the first ':' or '/' found in [0, end).

Note: Not thread-safe; the caller must ensure href is stable for the duration of the call.

Since: 0.1.0

Definition at line 140 of file reflow_link.c.

Referenced by internal_href_classify().

◆ internal_href_classify()

void internal_href_classify	(	const char *	href,
		uint32_t	len,
		reflow_href_kind_t *	out_kind,
		uint32_t *	out_path_len,
		uint32_t *	out_frag_off,
		uint32_t *	out_frag_len )

static

Core href split + classify (no validation; pure on the inputs).

Locates the fragment '#', detects a URI scheme, and classifies into one of reflow_href_kind_t. Factored out of reflow_href_split() so the public wrapper holds only the pointer validation (keeps each within the cognitive-complexity budget). The algorithm first scans for the first '#' character to separate the path part from the optional fragment. It then delegates scheme detection to internal_has_scheme() on the path sub-range. Based on whether a scheme, a fragment, and a non-empty path are present, one of the five reflow_href_kind_t values is written to out_kind. Fragment offset and length are written only when a '#' was found; otherwise the caller-initialized zeros remain unchanged.

Parameters

[in]	href	Href byte array; must not be NULL and len > 0.
[in]	len	Length of `href` in bytes; must be greater than 0.
[out]	out_kind	Receives the link classification result.
[out]	out_path_len	Receives the byte length of the path part (before '#').
[out]	out_frag_off	Receives the byte offset of the fragment (after '#'); 0 if none.
[out]	out_frag_len	Receives the byte length of the fragment; 0 if none.

Returns: Nothing.

Precondition: All pointer arguments are non-NULL.; len is greater than 0 (callers must guard before invoking).

Postcondition: out_kind is set to a valid reflow_href_kind_t value.; out_path_len reflects the number of bytes before the first '#' or len.

Note: Not thread-safe; the caller must ensure href is stable for the duration of the call.

Since: 0.1.0

Definition at line 186 of file reflow_link.c.

References internal_has_scheme(), k_reflow_href_chapter, k_reflow_href_chapter_fragment, k_reflow_href_empty, k_reflow_href_external, and k_reflow_href_fragment.

Referenced by reflow_href_split().

◆ reflow_find_anchor()

ra8_err_t reflow_find_anchor	(	const reflow_t *	engine,
		const char *	id,
		uint32_t	id_len,
		uint32_t *	out_page )

nodiscard

Find the page of a same-chapter id anchor (for #fragment jumps).

Linear-scans engine->anchors[] for an element whose captured id equals id (exact byte compare). Used to resolve a #frag link to the page holding the target element.

Parameters

[in]	engine	Initialized engine handle.
[in]	id	Fragment id bytes (no leading '#').
[in]	id_len	Length of `id`, bytes.
[out]	out_page	Receives the page index of the anchor.

Returns: ra8_err_t

Return values

k_ra8_ok	Anchor found; `*out_page` set.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_invalid_arg	`id_len` is 0.
k_ra8_err_not_found	No anchor matches `id`.

Precondition: engine is laid out; id / out_page are valid.; id_len > 0.

Postcondition: On success *out_page < engine page count.

Note: Read-only.

Since: 0.1.0

Definition at line 88 of file reflow_link.c.

References reflow_t::anchor_count, reflow_t::anchors, reflow_anchor_t::id_len, reflow_anchor_t::id_off, k_ra8_err_invalid_arg, k_ra8_err_not_found, k_ra8_ok, reflow_anchor_t::page_index, RA8_CHECK_NULL_PTR, s_tag_link, and reflow_t::text_pool.

Referenced by er_nav_fragment(), and main().

◆ reflow_hit_test_image()

ra8_err_t reflow_hit_test_image	(	const reflow_t *	engine,
		uint32_t	page_idx,
		int32_t	x,
		int32_t	y,
		uint32_t *	out_index )

nodiscard

Hit-test a point on a page against the laid-out <img> boxes (#478).

The sibling of reflow_hit_test_link, and the entry point of the reader's tap-to-zoom gesture: a tap that lands on a figure opens that figure full screen, at retained full resolution, rather than the column-scaled thumbnail the page shows. Walks engine->image_boxes[] for page_idx and returns the index of the first box containing (x, y). Coordinates are page-local – the same space reflow_render_page() uses – so subtract the render origin first if the page was drawn at an offset.

The index (rather than a copy of the box) is what a caller needs: it addresses engine->image_boxes[i] for the laid-out rectangle and its src_off / src_len href slice, which is how the tapped figure is resolved to the image a zoom source binds to.

Parameters

[in]	engine	Initialized engine handle.
[in]	page_idx	Page to test.
[in]	x	Page-local x, pixels.
[in]	y	Page-local y, pixels.
[out]	out_index	Receives the index into engine->image_boxes[].

Returns: ra8_err_t

Return values

k_ra8_ok	An image box contains the point; `*out_index` set.
k_ra8_err_null_ptr	`engine` or `out_index` is NULL.
k_ra8_err_not_found	No image box on `page_idx` contains the point.

Precondition: engine is initialized and laid out.; out_index is writable.

Postcondition: On success *out_index < engine->image_box_count.; On failure *out_index is unchanged.

Note: Read-only; safe to call between render passes. Earlier boxes win on overlap, matching reflow_hit_test_link and ra8_ui_hit_test.

Example:: uint32_t idx = 0U;

if (reflow_hit_test_image(engine, page, tx, ty, &idx) == k_ra8_ok) {

er_open_zoom(&engine->image_boxes[idx]);

}

k_ra8_ok
@ k_ra8_ok
Success – operation completed with all postconditions satisfied.
Definition ra8_err.h:119

reflow_hit_test_image
ra8_err_t reflow_hit_test_image(const reflow_t *engine, uint32_t page_idx, int32_t x, int32_t y, uint32_t *out_index)
Hit-test a point on a page against the laid-out <img> boxes (#478).
Definition reflow_link.c:63

See also: reflow_hit_test_link

Since: 0.1.0

Definition at line 63 of file reflow_link.c.

References reflow_image_box_t::h, reflow_t::image_box_count, reflow_t::image_boxes, k_ra8_err_not_found, k_ra8_ok, reflow_image_box_t::page_index, RA8_CHECK_NULL_PTR, s_tag_link, reflow_image_box_t::w, reflow_image_box_t::x, and reflow_image_box_t::y.

◆ reflow_hit_test_link()

ra8_err_t reflow_hit_test_link	(	const reflow_t *	engine,
		uint32_t	page_idx,
		int32_t	x,
		int32_t	y,
		uint32_t *	out_href_off,
		uint32_t *	out_href_len )

nodiscard

Hit-test a point on a page against the laid-out <a> link rectangles.

Walks engine->link_rects[] for page_idx and returns the href of the first rectangle containing (x, y). Coordinates are page-local (the same space reflow_render_page() uses); subtract the render origin first if the page was drawn at an offset. The href is returned as a slice into the engine text pool – read &engine->...text...[*out_href_off] for *out_href_len bytes via the engine, or pass it straight to reflow_href_split().

Parameters

[in]	engine	Initialized engine handle.
[in]	page_idx	Page to test.
[in]	x	Page-local x, pixels.
[in]	y	Page-local y, pixels.
[out]	out_href_off	Receives the href text-pool offset.
[out]	out_href_len	Receives the href length, bytes.

Returns: ra8_err_t

Return values

k_ra8_ok	A link rect contains the point; outputs set.
k_ra8_err_null_ptr	A required pointer is NULL.
k_ra8_err_not_found	No link rect on `page_idx` contains the point.

Precondition: engine is initialized and laid out.; out_href_off / out_href_len are writable.

Postcondition: On success the outputs slice the engine text pool.; On failure the outputs are unchanged.

Note: Read-only; safe to call between render passes.

Since: 0.1.0

Definition at line 36 of file reflow_link.c.

References reflow_link_rect_t::h, reflow_link_target_t::href_len, reflow_link_target_t::href_off, k_ra8_err_not_found, k_ra8_ok, reflow_t::link_rect_count, reflow_t::link_rects, reflow_t::link_targets, reflow_link_rect_t::page_index, RA8_CHECK_NULL_PTR, s_tag_link, reflow_link_rect_t::target, reflow_link_rect_t::w, reflow_link_rect_t::x, and reflow_link_rect_t::y.

Referenced by er_reading_link_tap(), and lk_probe_rect().

◆ reflow_href_split()

ra8_err_t reflow_href_split	(	const char *	href,
		uint32_t	len,
		reflow_href_kind_t *	out_kind,
		uint32_t *	out_path_len,
		uint32_t *	out_frag_off,
		uint32_t *	out_frag_len )

nodiscard

Split + classify an <a href> into a path part and a #fragment.

Pure string logic (no engine state): detects a URI scheme (external, unsupported), a leading '#' (same-chapter fragment), or an embedded '#' (chapter + fragment). The path part is href[0 .. *out_path_len); the fragment, if any, is href[*out_frag_off .. *out_frag_off + *out_frag_len) (excluding the '#').

Parameters

[in]	href	Href bytes (not NUL-terminated).
[in]	len	Length of `href`, bytes.
[out]	out_kind	Receives the classification.
[out]	out_path_len	Receives the path-part length (0 for fragment-only).
[out]	out_frag_off	Receives the fragment start offset (0 if none).
[out]	out_frag_len	Receives the fragment length (0 if none).

Returns: ra8_err_t

Return values

k_ra8_ok	Classified; all outputs set.
k_ra8_err_null_ptr	A required pointer is NULL.

Precondition: href holds len bytes; all out pointers are writable.

Postcondition: *out_kind reflects the href shape; the spans index within href.

Note: Pure function; thread-safe.

Since: 0.1.0

Definition at line 218 of file reflow_link.c.

References internal_href_classify(), k_ra8_ok, k_reflow_href_empty, RA8_CHECK_NULL_PTR, and s_tag_link.

Referenced by er_reading_link_tap(), and lk_probe_rect().

Variable Documentation

◆ s_tag_link

const char* const s_tag_link = "ra8_link"

static

Log tag for the link/anchor query module.

Definition at line 34 of file reflow_link.c.

Referenced by reflow_find_anchor(), reflow_hit_test_image(), reflow_hit_test_link(), and reflow_href_split().

Functions

Variables

Detailed Description

Function Documentation

◆ internal_has_scheme()

◆ internal_href_classify()

◆ reflow_find_anchor()

◆ reflow_hit_test_image()

◆ reflow_hit_test_link()

◆ reflow_href_split()

Variable Documentation

◆ s_tag_link