Pikchr UI Subset

Status: Normative
Version: PUS-1 (2026-08-16)
Parent decision: D3.2 — GP-Crystal Design Overview §3

1. Purpose

This page defines the Pikchr UI Subset (PUS-1): the exact set of Pikchr constructs that GP-Crystal UI blocks may emit. The subset is sized so that both target renderers can faithfully express every construct:

• Web renderer — Fossil's built-in Pikchr→SVG pipeline.
• Embedded renderer — a Pikchr-subset→lvgl-crystal translator targeting badge-class devices (absolute-positioned, static layout; reflow out of scope).

Any Pikchr construct not listed here is excluded. UI block emitters MUST NOT emit excluded constructs.

2. Element Table

2.1 box

box wid 1.20 ht 0.40 rad 0.03 with .nw at (0.10,3.20) fill 0x4C97FF color 0x4C97FF

lvgl-crystal mapping:

2.2 text

text "Start" color 0xFFFFFF at (0.70,3.00)

lvgl-crystal mapping: Lvgl::Widgets::Label.new(parent) with .text = <string> and set_style_text_color(color). Position: set_pos at the resolved center minus half the text bounds (font-dependent; best-effort on embedded).

Overlap rule: when a text element's bounding box lies within a box element's bounds, the lvgl translator MUST create the label as a child of that box widget, not as a sibling on the screen root.

2.3 line

line from (0.10,2.00) to (2.90,2.00) color 0xCCCCCC

lvgl-crystal mapping: LibLvgl.lv_line_create(parent_ptr) with a two-point lv_point_t array. (Lvgl::Widgets::Line is not yet a named wrapper; the translator calls LibLvgl directly.)

2.4 arrow

An arrow is a line with one or both arrowheads. All line attributes apply, plus:

arrow from (0.50,1.50) to (2.50,1.50) color 0x4C97FF

lvgl-crystal mapping: same as line; arrowheads are drawn as small filled triangles computed from the endpoint direction vector, rendered as additional lv_line segments.

2.5 circle

circle rad 0.20 at (1.50,2.80) fill 0xFF8C1A color 0xFF8C1A

lvgl-crystal mapping: LibLvgl.lv_arc_create(parent_ptr) with arc range set to 0–360° (full circle); rad × 2 maps to set_size. The element is circle, not ellipse, precisely because lv_arc is circular — a non-circular ellipse has no faithful lvgl rendering, so the subset does not offer one.

3. Layout Resolution Rule

Pikchr's default placement model chains elements relative to previously placed objects. PUS-1 forbids implicit chaining and mandates explicit absolute coordinates.

Rule 1 — Mandatory at clause. Every element MUST include an explicit at (x, y) clause where both coordinates are numeric literals. Implicit Pikchr placement (chaining from the previous element's edge) is excluded.

Rule 2 — Mandatory scale line. Every PUS-1 diagram MUST open with:

scale = <N>

This resolves the pixel formula (both renderers apply it identically):

px = round(pikchr_inches × 72 × scale)

Typical value: scale = 0.75 (matches the gpcr renderer's current default).

Rule 3 — Y-axis inversion (lvgl only). Pikchr's origin is bottom-left; lvgl's is top-left. The embedded translator applies:

px_x = round(x_in × 72 × scale)
px_y = round((canvas_height_in − y_in) × 72 × scale)

canvas_height_in is computed from the bounding box of all declared elements.

Rule 4 — Anchor resolution. The translator resolves each element's top-left corner from the declared at point and with anchor before calling set_pos:

• with .nw: at is the top-left corner directly.
• with .center or no with: top-left = at − (wid/2, ht/2).
• Other anchors: computed geometrically from element dimensions.

Rule 5 — No reflow. Dynamic layout (text wrapping, flex, grid) is out of scope for PUS-1. Screens are authored at fixed pixel dimensions matched to the target display.

4. Interactivity Annotation Convention

Pikchr only draws; it carries no event semantics. PUS-1 annotates interactive elements via a trailing Pikchr comment on the same source line as the element. Both the web JS layer and the lvgl event handler parse the identical comment text from the same Pikchr source, making the annotation the single source of truth for both renderers.

4.1 Syntax

<pikchr-element-line> # [id=<name>] [op=<json>] [ev=<event>]

Fields are space-separated within the comment. At least one of id= or op= MUST be present for the comment to be treated as an annotation (plain comments without these fields are ignored).

4.2 Web renderer behavior

A single external JS asset (no inline scripts; CSP-safe per D3.1) scans the Pikchr source that produced each rendered SVG page. For each annotated element it:

1. Locates the SVG element whose id attribute matches id=<name>.
2. Attaches a click listener that HTTP-POSTs the JSON from op= to the management API endpoint (ticket 21dfd164d6).
3. Sets cursor: pointer on the element.

Element mapping is ordinal. Pikchr emits no id attributes in its SVG output; it does, however, emit graphics elements in source order. The scanner therefore reads the diagram's Pikchr source (the page embeds it — Fossil's toggle fences already do), and maps the k-th shape-producing line of the source to the k-th top-level graphics element of the SVG. id= is a pure annotation-namespace identifier and has no relationship to Pikchr tags:

box wid 1.20 ht 0.40 ... # id=blink_btn op={"op":"call","target":"blink"}

Pikchr tags (Label:) remain available for positioning within the diagram; note that Pikchr requires tag names to begin with an uppercase letter, another reason they are unsuitable as annotation ids.

4.3 lvgl-crystal behavior

The translator parses annotation comments before constructing widgets. For each annotated element it:

1. Creates the widget per §2.
2. Registers a Lvgl::Event subscription for the event code named by ev= (default Code::Clicked) on the new widget.
3. On event fire, passes the op= JSON string to the local op-apply engine (the same engine that processes voice and model edits — Design Overview §1).

4.4 Annotated diagram example

scale = 0.75

box wid 1.20 ht 0.40 rad 0.03 with .nw at (0.10,3.20) fill 0x4C97FF color 0x4C97FF # id=start_btn op={"op":"call","target":"blink"}
text "Start" color 0xFFFFFF at (0.70,3.00)

box wid 1.20 ht 0.40 rad 0.03 with .nw at (1.50,3.20) fill 0xFF6680 color 0xFF6680 # id=stop_btn op={"op":"call","target":"stop_blink"}
text "Stop" color 0xFFFFFF at (2.10,3.00)

circle rad 0.15 at (2.75,3.05) fill 0xFF0000 color 0xFF0000 # id=led_status

line from (0.10,2.80) to (3.00,2.80) color 0xCCCCCC

In this example start_btn and stop_btn are interactive (Button on lvgl; click listeners in the web layer); led_status has an id for programmatic update but no op= (static on lvgl; addressable by the JS layer for visual state changes via SSE re-render); the line is a pure static separator.

5. Explicit Exclusions

5.1 Excluded shape keywords

ellipse, arc, cylinder, file, oval, diamond, dot, spline.

ellipse is excluded because lvgl has no ellipse (lv_arc is circular) — use circle. arc is excluded because Pikchr renders arcs as open paths with fill:none regardless of the fill attribute, so no filled dual rendering exists.

5.2 Excluded attributes and modifiers

5.3 Excluded placement forms

5.4 Excluded control flow and macros

define, loop, until, print, assert.

5.5 Excluded interactivity

6. Version History

PUS-2 will be drafted once the pixel formula is validated on real lvgl-crystal hardware and at least one working UI block has been rendered on both targets.

First artifact of D3.2. Implementation in a separate ticket.