3 Architecture

Virgil edited this page 2026-02-19 16:41:13 +00:00

Table of Contents

• Architecture
• HLCRF Layout Model
• Variant Selection
• Creating Layouts
• Semantic HTML Output
• Block IDs
• Nested Layouts
• Responsive Variants
• Thread Safety
• Security Model

Architecture

The HLCRF layout system implements a deterministic, path-aware region compositor for semantic HTML5 output.

See also: Home | Node-API | Pipeline | WebAssembly | Code-Generation

HLCRF Layout Model

HLCRF stands for Header-Left-Content-Right-Footer — five semantic regions that compose a page layout:

┌─────────────────────────────┐
│           Header            │  role="banner"
├───────┬─────────────┬───────┤
│       │             │       │
│ Left  │   Content   │ Right │  Left/Right: role="complementary"
│       │             │       │  Content: role="main"
├───────┴─────────────┴───────┤
│           Footer            │  role="contentinfo"
└─────────────────────────────┘

Variant Selection

Not every page needs all 5 regions. The variant string controls which slots are active:

Variant	Regions	Use Case
HLCRF	All five	Full dashboard layout
HCF	Header, Content, Footer	Standard page
HCR	Header, Content, Right	Page with sidebar
C	Content only	Minimal embed
LCR	Left, Content, Right	Three-column

Creating Layouts

layout := html.NewLayout("HCF").
    H(html.El("nav", html.Text("nav.home"))).
    C(html.El("main",
        html.El("h1", html.Text("page.title")),
        html.El("p", html.Text("page.intro")),
    )).
    F(html.El("footer", html.Text("site.copyright")))

Each slot method (H, L, C, R, F) appends nodes and returns the layout for chaining.

Semantic HTML Output

The renderer produces proper HTML5 with ARIA landmarks:

<header role="banner" data-block="H-0">
  <nav>Home</nav>
</header>
<main role="main" data-block="C-0">
  <h1>Page Title</h1>
  <p>Introduction text</p>
</main>
<footer role="contentinfo" data-block="F-0">
  &copy; 2026
</footer>

Block IDs

Every rendered region gets a deterministic data-block attribute for JavaScript anchoring:

Block ID	Meaning
H-0	Header, first node
L-0	Left sidebar, first node
C-0	Content, first node
C-1	Content, second node
R-0	Right sidebar, first node
F-0	Footer, first node

Nested Layouts

Layouts can nest inside other layouts. Block IDs chain to form a path:

inner := html.NewLayout("C").
    C(html.El("div", html.Text("nested.content")))

outer := html.NewLayout("HCF").
    H(html.El("nav", html.Text("nav.home"))).
    C(inner).
    F(html.El("small", html.Text("site.footer")))

The inner content gets block ID C-0-C-0 (Content slot of outer, Content slot of inner). ParseBlockID("C-0-C-0") returns the byte sequence for programmatic traversal.

Responsive Variants

The Responsive type wraps multiple layout variants for adaptive rendering:

resp := html.NewResponsive().
    Variant("desktop", html.NewLayout("HLCRF").
        H(header).L(sidebar).C(content).R(aside).F(footer)).
    Variant("mobile", html.NewLayout("HCF").
        H(header).C(content).F(footer))

Each variant renders independently. Use CompareVariants() to measure grammar similarity between variants via GrammarImprint (see Pipeline).

Thread Safety

Layouts are cloned before path modification during rendering, making them safe for concurrent use. The Context carries per-request state (identity, locale, entitlements) without mutating the layout tree.

Security Model

• Text() nodes are HTML-escaped via escapeHTML() — XSS-safe by default
• El() attribute values are escaped via escapeAttr()
• Void elements (br, img, hr, input, etc.) properly self-close
• Attribute output is deterministic (sorted keys)
• Raw() is the only escape hatch — caller is responsible for sanitisation