wijjit.core.renderer.Renderer

class wijjit.core.renderer.Renderer(template_dir=None, autoescape=False, auto_reload=False, *, strict_undefined=False)[source]

Template renderer using Jinja2.

This class manages Jinja2 template rendering with support for both string templates and file-based templates.

Parameters:

template_dir (str, optional) – Directory containing template files
autoescape (bool, optional) – Whether to enable autoescaping (default: False for terminal output)
auto_reload (bool, optional) – Whether Jinja2 reloads file templates when they change on disk (default: False). Useful during development; maps to the TEMPLATE_AUTO_RELOAD config key.
strict_undefined (bool, optional keyword-only) – Whether the Jinja2 environment uses jinja2.StrictUndefined (default: False). In strict mode, referencing an undefined template name (e.g. {{ typo_var }}) raises jinja2.UndefinedError at render time, surfacing typos instead of silently rendering an empty string. The production default is lenient (jinja2.Undefined) so that one bad key cannot crash a running TUI; strict mode is enabled for development (DEBUG) and by the devtools validator.

Variables:

env (jinja2.Environment) – The Jinja2 environment
strict_undefined (bool) – Whether undefined template names raise at render time.
_string_templates (dict) – Cache of string templates

__init__(template_dir=None, autoescape=False, auto_reload=False, *, strict_undefined=False)[source]

Parameters:

template_dir (str | None)
autoescape (bool)
auto_reload (bool)
strict_undefined (bool)

Return type:

None

Methods

`__init__`([template_dir, autoescape, ...])
`add_filter`(name, func)	Add a custom filter to the Jinja2 environment.
`add_global`(name, value)	Add a global variable to the Jinja2 environment.
`clear_cache`()	Clear the template cache.
`clear_element_cache`()	Clear the reconciler element cache and VNode tree.
`composite_overlays`(base_output, ...[, ...])	Composite overlay elements on top of base output.
`get_buffer_as_text`()	Get the last rendered buffer as plain text (for testing).
`get_extension_tag_names`()	Return the set of Jinja2 tag names registered by Wijjit extensions.
`get_last_buffer`()	Get the last rendered buffer for external diff rendering.
`invalidate_display`()	Discard the cached on-screen buffers so the next render is full.
`render_file`(template_name[, context])	Render a template from a file.
`render_string`(template_string[, context])	Render a template from a string.
`render_with_layout`([template_string, ...])	Render a template with layout engine support.

get_extension_tag_names()[source]

Return the set of Jinja2 tag names registered by Wijjit extensions.

Useful for callers that need to determine whether a template uses any Wijjit-specific tag (and therefore must be routed through the layout pipeline rather than plain Jinja2 string rendering).

Returns:: Every tag name registered by the Wijjit extension classes (e.g. "frame", "textinput", "button").
Return type:: set[str]

render_string(template_string, context=None)[source]

Render a template from a string.

Parameters:

template_string (str) – The template string to render
context (dict, optional) – Context variables for template rendering

Returns:

The rendered template output

Return type:

str

render_file(template_name, context=None)[source]

Render a template from a file.

Parameters:

template_name (str) – Name of the template file
context (dict, optional) – Context variables for template rendering

Returns:

The rendered template output

Return type:

str

Raises:

jinja2.TemplateNotFound – If the template file doesn’t exist

add_filter(name, func)[source]

Add a custom filter to the Jinja2 environment.

Parameters:

name (str) – Name of the filter
func (Callable) – Filter function

Return type:

None

add_global(name, value)[source]

Add a global variable to the Jinja2 environment.

Parameters:

name (str) – Name of the global variable
value (Any) – Value of the global variable

Return type:

None

render_with_layout(template_string='', context=None, width=None, height=None, template_name=None, allow_incremental=False)[source]

Render a template with layout engine support.

This method handles the full pipeline for layout-based templates: 1. Create layout context 2. Render template (building layout tree) 3. Run layout engine to calculate positions 4. Compose final output from positioned elements

Parameters:

template_string (str, optional) – The template string to render (use this OR template_name)
context (dict, optional) – Context variables for template rendering
width (int, optional) – Available width (default: terminal width)
height (int, optional) – Available height (default: terminal height)
template_name (str, optional) – Name of template file to load from template_dir (use this OR template_string)
allow_incremental (bool)

Returns:

Rendered output, list of elements with bounds, and layout context containing overlay information from template tags

Return type:

tuple of (str, list of Element, LayoutContext)

get_last_buffer()[source]

Get the last rendered buffer for external diff rendering.

Returns:: Last rendered buffer, or None if not yet rendered
Return type:: ScreenBuffer or None

invalidate_display()[source]

Discard the cached on-screen buffers so the next render is full.

Diff rendering compares the new frame against _last_displayed_buffer and emits only the cells that changed, so bytes written to the terminal out-of-band (foreign stdout, a stray traceback, a subprocess) are invisible to the differ and persist on screen. Clearing the cached buffers forces the next render_diff down the _full_render path - a screen clear plus a complete repaint - which overwrites any such bytes. Both the base and displayed buffers are cleared so overlay compositing also starts from a clean slate.

Return type:: None

get_buffer_as_text()[source]

Get the last rendered buffer as plain text (for testing).

Returns:: Plain text representation of the last buffer
Return type:: str

Notes

This is primarily used for test assertions where you want to check for visible text content without parsing ANSI escape sequences. Returns empty string if no buffer has been rendered yet.

Examples

>>> renderer = Renderer()
>>> output, _, _ = renderer.render_with_layout(template, 80, 24)
>>> text = renderer.get_buffer_as_text()
>>> 'Welcome' in text
True

composite_overlays(base_output, overlay_elements, width, height, apply_dimming=False, dim_factor=0.6, force_full_redraw=False)[source]

Composite overlay elements on top of base output.

This method renders overlays on top of the base UI output, optionally applying backdrop dimming for modal effects.

Parameters:

base_output (str) – Base UI output (ANSI string or newline-separated lines)
overlay_elements (list of Element) – Overlay elements with assigned bounds (in z-order, lowest first)
width (int) – Screen width
height (int) – Screen height
apply_dimming (bool) – Whether to dim the base output (for modal backdrops)
dim_factor (float) – Dimming intensity (0.0 = black, 1.0 = original). Default is 0.6.
force_full_redraw (bool) – Force full screen redraw instead of diff rendering

Returns:

Composited output with overlays on top

Return type:

str

Notes

Overlays are rendered in the order provided (first = bottom, last = top). If apply_dimming is True, the base output is dimmed before overlays are composited.

Overlays are composited directly on the cell buffer for efficient rendering.

clear_cache()[source]

Clear the template cache.

Return type:: None

clear_element_cache()[source]

Clear the reconciler element cache and VNode tree.

This should be called when navigating to a different view to avoid stale ephemeral state transfer.

Return type:: None