reflow_types.h File Reference

Reflow-engine data model: enums, structs, typedefs, and the handle. More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_err.h"
#include "ra8_glyph_atlas.h"
#include "reflow_css.h"
#include "reflow_image.h"

Include dependency graph for reflow_types.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	reflow_token_t
	One parsed token in the engine's token stream. More...
struct	reflow_glyph_t
	One positioned glyph after layout. More...
struct	reflow_page_t
	Index range of glyphs that belong to one page. More...
struct	reflow_image_box_t
	One laid-out <img> rectangle (decoded + blitted at render time). More...
struct	reflow_link_target_t
	One distinct <a href> destination interned during a parse. More...
struct	reflow_link_rect_t
	One tappable rectangle covering a run of <a> glyphs on a page. More...
struct	reflow_anchor_t
	A laid-out element id, for same-chapter #fragment jumps. More...
struct	reflow_face_t
	One registered embedded @font-face typeface (#109). More...
struct	reflow_t
	Reflow / pagination engine state. More...

Typedefs
typedef ra8_err_t(*	reflow_image_loader_fn) (void *ctx, const char *href, uint32_t href_len, const uint8_t **out_bytes, size_t *out_len)
	Resolve an <img src> href to its encoded image bytes.
typedef ra8_err_t(*	reflow_css_loader_fn) (void *ctx, const char *href, uint32_t href_len, const uint8_t **out_bytes, size_t *out_len)
	External-stylesheet byte loader for <link rel="stylesheet" href>.

Enumerations
enum	reflow_limits_t : uint32_t {   k_reflow_max_tokens = 4096U ,   k_reflow_text_pool_bytes = 65536U ,   k_reflow_max_glyphs = 32768U ,   k_reflow_max_pages = 256U ,   k_reflow_max_lines_per_page = 96U ,   k_reflow_max_images = 64U ,   k_reflow_max_links = 255U ,   k_reflow_max_link_rects = 512U ,   k_reflow_max_anchors = 256U ,   k_reflow_max_faces = 8U }
	Static-allocation caps for the reflow engine. More...
enum	reflow_layout_t : uint16_t {   k_reflow_margin_px = 16U ,   k_reflow_line_spacing_num = 12U ,   k_reflow_line_spacing_den = 10U ,   k_reflow_paragraph_gap_px = 8U ,   k_reflow_indent_px = 24U ,   k_reflow_default_font_px = 18U ,   k_reflow_min_font_px = 8U ,   k_reflow_max_font_px = 96U ,   k_reflow_min_font_bytes = 16U ,   k_reflow_h1_scale_pct = 200U ,   k_reflow_h2_scale_pct = 175U ,   k_reflow_h3_scale_pct = 150U ,   k_reflow_h4_scale_pct = 125U ,   k_reflow_h5_scale_pct = 110U ,   k_reflow_h6_scale_pct = 100U ,   k_reflow_pct_full = 100U }
	Layout-axis named constants used by the line-break engine. More...
enum	reflow_html_tag_t : uint8_t {   k_reflow_tag_unknown = 0U ,   k_reflow_tag_p = 1U ,   k_reflow_tag_h1 = 2U ,   k_reflow_tag_h2 = 3U ,   k_reflow_tag_h3 = 4U ,   k_reflow_tag_h4 = 5U ,   k_reflow_tag_h5 = 6U ,   k_reflow_tag_h6 = 7U ,   k_reflow_tag_em = 8U ,   k_reflow_tag_strong = 9U ,   k_reflow_tag_b = 10U ,   k_reflow_tag_i = 11U ,   k_reflow_tag_br = 12U ,   k_reflow_tag_hr = 13U ,   k_reflow_tag_ul = 14U ,   k_reflow_tag_ol = 15U ,   k_reflow_tag_li = 16U ,   k_reflow_tag_blockquote = 17U ,   k_reflow_tag_a = 18U ,   k_reflow_tag_img = 19U ,   k_reflow_tag_table = 20U ,   k_reflow_tag_tr = 21U ,   k_reflow_tag_td = 22U ,   k_reflow_tag_th = 23U ,   k_reflow_tag_link = 24U }
	Recognised HTML element kinds. More...
enum	reflow_font_style_t : uint8_t {   k_reflow_style_normal = 0U ,   k_reflow_style_bold = 1U << 0U ,   k_reflow_style_italic = 1U << 1U ,   k_reflow_style_underline = 1U << 2U }
	Inline font-style flags (bitfield). More...
enum	reflow_face_pack_t : uint8_t {   k_reflow_face_shift = 4U ,   k_reflow_face_mask = 0x0FU }
	How a per-run embedded-face index is packed into a glyph/token style. More...
enum	reflow_align_t : uint8_t {   k_reflow_align_left = 0U ,   k_reflow_align_right = 1U ,   k_reflow_align_center = 2U ,   k_reflow_align_justify = 3U }
	Block text alignment (from an inline style="text-align:..."). More...
enum	reflow_token_kind_t : uint8_t {   k_reflow_tok_block_start = 0U ,   k_reflow_tok_block_end = 1U ,   k_reflow_tok_text = 2U ,   k_reflow_tok_break = 3U ,   k_reflow_tok_rule = 4U ,   k_reflow_tok_image = 5U }
	Parsed token classification. More...
enum	reflow_color_t : uint32_t { k_reflow_color_inherit = 0xFFFFFFFFU }
	Sentinel marking a token / run with no CSS colour. More...
enum	reflow_href_kind_t : uint8_t {   k_reflow_href_empty = 0U ,   k_reflow_href_fragment = 1U ,   k_reflow_href_chapter = 2U ,   k_reflow_href_chapter_fragment = 3U ,   k_reflow_href_external = 4U }
	Classification of an in-content <a href> target. More...
enum	reflow_face_pad_t : uint8_t { k_reflow_face_pad8 = 7 }
	Padding geometry for reflow_face_t. More...

Detailed Description

Reflow-engine data model: enums, structs, typedefs, and the handle.

This sub-header holds the data model for the reflow HTML / CSS reflow

• pagination engine: the compile-time limit enums, the parsed-token and positioned-glyph structs, the dependency-injection loader function-pointer typedefs, and the engine handle (reflow_t) itself. It is split out of the umbrella reflow.h so that header stays small; consumers still include reflow.h and never reference this file directly.

[Ring 4 / Reflow] {World: NS}

Copyright

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

Since

0.1.0

Definition in file reflow_types.h.

Typedef Documentation

reflow_css_loader_fn

typedef ra8_err_t(* reflow_css_loader_fn) (void *ctx, const char *href, uint32_t href_len, const uint8_t **out_bytes, size_t *out_len)

External-stylesheet byte loader for <link rel="stylesheet" href>.

Dependency-injection seam (NASA P10 Rule 9 deviation: function pointer for testability / DIP), mirroring reflow_image_loader_fn. The consumer wires this to its EPUB resource loader; the engine calls it while tokenizing a chapter, when a <link rel="stylesheet" href="X"> is seen in document order, and parses the returned CSS into the chapter's sheet at that position (so a later <style> block / inline style= correctly override it). The returned buffer is only read, never freed, by the engine and need only stay valid until the call returns.

Parameters

[in]	ctx	Opaque context passed to reflow_set_css_loader().
[in]	href	Stylesheet href string (not NUL-terminated).
[in]	href_len	Length of href, bytes.
[out]	out_bytes	Receives a pointer to the CSS text bytes.
[out]	out_len	Receives the CSS byte count.

Returns

ra8_err_t; k_ra8_ok on success, any error to skip the stylesheet.

Note

The engine treats any non-k_ra8_ok return as "stylesheet unavailable" and continues with only the inline rules.

Since

0.1.0

Definition at line 334 of file reflow_types.h.

reflow_image_loader_fn

typedef ra8_err_t(* reflow_image_loader_fn) (void *ctx, const char *href, uint32_t href_len, const uint8_t **out_bytes, size_t *out_len)

Resolve an <img src> href to its encoded image bytes.

Dependency-injection seam (NASA P10 Rule 9 deviation: function pointer for testability / DIP). The consumer wires this to its EPUB resource loader; the engine calls it at layout time (to probe intrinsic size) and at render time (to fetch bytes for the decode). The returned buffer must remain valid until the call returns and is only read, never freed, by the engine.

Parameters

[in]	ctx	Opaque context passed to reflow_set_image_loader().
[in]	href	Image src string (not NUL-terminated).
[in]	href_len	Length of href, bytes.
[out]	out_bytes	Receives a pointer to the encoded image bytes.
[out]	out_len	Receives the encoded byte count.

Returns

ra8_err_t; k_ra8_ok on success, any error to skip the image.

Note

The engine treats any non-k_ra8_ok return as "image unavailable" and falls back to a placeholder advance.

Since

0.1.0

Definition at line 304 of file reflow_types.h.

Enumeration Type Documentation

reflow_align_t

enum reflow_align_t : uint8_t

Block text alignment (from an inline style="text-align:...").

Carried on a block-start token (its reserved byte) and applied as a per-line pass: centre/right shift every glyph on the line; justify spreads the slack across inter-word gaps on full (wrapped) lines, leaving the last line of a paragraph left-aligned. The default is left (identical to the historical greedy layout, so unaligned content is byte-stable).

Enumerator
k_reflow_align_left	Left (default, ragged right).
k_reflow_align_right	Right-aligned.
k_reflow_align_center	Centred.
k_reflow_align_justify	Justified (last line left-aligned).

Definition at line 168 of file reflow_types.h.

reflow_color_t

enum reflow_color_t : uint32_t

Sentinel marking a token / run with no CSS colour.

A text token's color field holds a 0xRRGGBB CSS colour (#111 / #140) or this sentinel, in which case the renderer falls back to the engine body colour (or link colour for an <a> run). 0xFFFFFFFF is outside the 24-bit RGB range, so it can never collide with a real colour.

Enumerator
k_reflow_color_inherit	No per-run CSS colour.

Definition at line 208 of file reflow_types.h.

reflow_face_pack_t

enum reflow_face_pack_t : uint8_t

How a per-run embedded-face index is packed into a glyph/token style.

The emphasis bits (bold/italic/underline) occupy bits 0-2 of the style byte; bits 4-7 are free, so the selected embedded-face index (0 = the engine's bound default face, 1..k_reflow_max_faces = a registered @font-face) rides in the high nibble (#109). Single-face content registers no faces, so the nibble is always 0 – the cached / default render path is byte-identical.

Enumerator
k_reflow_face_shift	Bit position of the face index in style.
k_reflow_face_mask	Face-index mask once shifted down.

Definition at line 153 of file reflow_types.h.

reflow_face_pad_t

enum reflow_face_pad_t : uint8_t

Padding geometry for reflow_face_t.

Names the trailing-pad byte count that rounds reflow_face_t up to an 8-byte stride (one pointer, one size_t, one uint8_t index, then k_reflow_face_pad8 bytes of padding).

See also

reflow_face_t

Enumerator
k_reflow_face_pad8	Pad bytes to reach an 8-byte struct stride.

Definition at line 411 of file reflow_types.h.

reflow_font_style_t

enum reflow_font_style_t : uint8_t

Inline font-style flags (bitfield).

Used by both the parse pass (active style on the cursor) and the render pass (per-glyph style stamp). v1 does not yet load separate bold / italic TTFs; the flag is stored so the renderer can later pick the right face without reflow.

Enumerator
k_reflow_style_normal	No emphasis.
k_reflow_style_bold	Bold face.
k_reflow_style_italic	Italic face.
k_reflow_style_underline	Underlined run.

Definition at line 135 of file reflow_types.h.

reflow_href_kind_t

enum reflow_href_kind_t : uint8_t

Classification of an in-content <a href> target.

Enumerator
k_reflow_href_empty	Empty / whitespace-only href.
k_reflow_href_fragment	"#id" – same-chapter anchor.
k_reflow_href_chapter	"path" – another chapter, no frag.
k_reflow_href_chapter_fragment	"path#id" – chapter + anchor.
k_reflow_href_external	Has a URI scheme (http:, mailto:).

Definition at line 388 of file reflow_types.h.

reflow_html_tag_t

enum reflow_html_tag_t : uint8_t

Recognised HTML element kinds.

Tags outside this list are treated as transparent flow-through containers (children still emit, the tag itself contributes no styling).

Enumerator
k_reflow_tag_unknown	Anything not in this enum.
k_reflow_tag_p	Paragraph block.
k_reflow_tag_h1	Heading level 1.
k_reflow_tag_h2	Heading level 2.
k_reflow_tag_h3	Heading level 3.
k_reflow_tag_h4	Heading level 4.
k_reflow_tag_h5	Heading level 5.
k_reflow_tag_h6	Heading level 6.
k_reflow_tag_em	Italic emphasis (inline).
k_reflow_tag_strong	Bold emphasis (inline).
k_reflow_tag_b	Bold (inline).
k_reflow_tag_i	Italic (inline).
k_reflow_tag_br	Line break (void).
k_reflow_tag_hr	Horizontal rule (void).
k_reflow_tag_ul	Unordered list block.
k_reflow_tag_ol	Ordered list block.
k_reflow_tag_li	List item.
k_reflow_tag_blockquote	Blockquote indent.
k_reflow_tag_a	Anchor (renders underlined).
k_reflow_tag_img	Image (placeholder rect).
k_reflow_tag_table	Table (grid layout).
k_reflow_tag_tr	Table row.
k_reflow_tag_td	Table cell.
k_reflow_tag_th	Table header cell.
k_reflow_tag_link	<link> (void; stylesheet ref).

Definition at line 97 of file reflow_types.h.

reflow_layout_t

enum reflow_layout_t : uint16_t

Layout-axis named constants used by the line-break engine.

These values name the magic numbers that would otherwise show up in the layout pass: page margin, line-spacing multiplier numerator / denominator, default font size, and the heading multipliers H1..H6.

Enumerator
k_reflow_margin_px	Page edge inset, pixels.
k_reflow_line_spacing_num	Line height numerator (= 1.2x).
k_reflow_line_spacing_den	Line height denominator.
k_reflow_paragraph_gap_px	Vertical gap after a block.
k_reflow_indent_px	Indent for blockquote / li.
k_reflow_default_font_px	Default body font size.
k_reflow_min_font_px	Smallest accepted font size.
k_reflow_max_font_px	Largest accepted font size.
k_reflow_min_font_bytes	Smallest plausible font blob.
k_reflow_h1_scale_pct	H1 size = 200 % of body.
k_reflow_h2_scale_pct	H2 size = 175 % of body.
k_reflow_h3_scale_pct	H3 size = 150 % of body.
k_reflow_h4_scale_pct	H4 size = 125 % of body.
k_reflow_h5_scale_pct	H5 size = 110 % of body.
k_reflow_h6_scale_pct	H6 size = 100 % of body.
k_reflow_pct_full	Percentage denominator.

Definition at line 69 of file reflow_types.h.

reflow_limits_t

enum reflow_limits_t : uint32_t

Static-allocation caps for the reflow engine.

The engine holds a fixed number of parsed tokens, positioned glyphs, and pages. Anything bigger is rejected with k_ra8_err_no_mem. Sized to fit the EK-RA8D2's 2 MB SRAM with comfortable headroom.

Enumerator
k_reflow_max_tokens	Max parsed token count.
k_reflow_text_pool_bytes	Bytes of text pool.
k_reflow_max_glyphs	Total positioned glyphs.
k_reflow_max_pages	Max paginated pages.
k_reflow_max_lines_per_page	Lines per page upper bound.
k_reflow_max_images	Max laid-out <img> boxes.
k_reflow_max_links	Max distinct <a href> per chapter.
k_reflow_max_link_rects	Max positioned link rectangles.
k_reflow_max_anchors	Max id= anchor positions.
k_reflow_max_faces	Max embedded @font-face typefaces.

Definition at line 47 of file reflow_types.h.

reflow_token_kind_t

enum reflow_token_kind_t : uint8_t

Parsed token classification.

The parser converts the markup into a flat token stream. Block-start and block-end tokens carry an reflow_html_tag_t; inline tokens carry text (a slice of the engine text pool) plus a font-style stamp.

Enumerator
k_reflow_tok_block_start	Open of a block-flow element.
k_reflow_tok_block_end	Close of a block-flow element.
k_reflow_tok_text	Text run (slice into pool).
k_reflow_tok_break	Forced line break (<br>).
k_reflow_tok_rule	Horizontal rule (<hr>).
k_reflow_tok_image	Image placeholder (<img>).

Definition at line 185 of file reflow_types.h.