# WEB Compiler Reference For LLM Agents
This document is a compact but comprehensive reference for generating valid WEB source for the current compiler implementation.
Use this when you need to:
- write `.web` source
- predict what `compiler.js` will emit
- understand which constructs affect HTML vs CSS
- use compile-time JavaScript safely
- avoid features the compiler does not support
This is an implementation-oriented reference, not a marketing overview.
## 1. Fast Mental Model
WEB has three practical entry points:
- legacy script mode: `layout.web` -> `index.html`, `styles.css`
- CLI mode: `home.web` -> `home.html`, `home.css`
- CLI scaffold mode: `web init [directory]` creates `index.web`, `web-lang-agents.md`, and then compiles to `index.html` plus `index.css` in the chosen project directory
Run:
```bash
node compiler.js
web init
web init .
web init website
web home.web
web home
web .
web ./code/*
```
The compiler pipeline is:
1. tokenize source
2. parse into a small AST
3. build a variable table
4. build a type symbol table
5. build the HTML document model
6. build the CSS style model
7. emit `index.html`
8. emit `styles.css`
Generated HTML shell:
- ``
- ``
- ``
- ``
- fixed `WEB Output`
- fixed stylesheet link to `styles.css`
- top-level `::head` entries are rendered before ``
- all rendered WEB nodes are inserted inside ``
- top-level `::script` blocks are rendered near the end of ``
Key idea:
- one optional top-level `define { ... }` block owns variables, type declarations, and style inheritance
- normal WEB blocks describe DOM structure and CSS
- top-level `html { ... }` and `* { ... }` describe global CSS selectors only
- `::attrs { ... }` adds real HTML attributes to normal WEB nodes
- `::head { ... }` adds literal `meta` and `link` tags to `` without entering the CSS pipeline
- `::script { ... }` adds literal `` tags without entering the CSS pipeline
- `derivedName extends baseName;` declarations still describe CSS inheritance only, and they only appear inside `define { ... }`
- `styles { ... }`, `::pseudo`, and `::media` describe CSS only
- `::keyframes` describes global animation blocks only
- `js\`...\`` runs at compile time, never in the browser
If you remember only one rule, remember this:
- HTML structure comes from normal DOM-scope paths
- CSS comes from property assignments plus style scopes, pseudo blocks, media blocks, and raw CSS
## 2. Minimal Working Shape
This is the simplest useful WEB file shape:
```web
define {
@pageWidth = "960px";
Main pageMain;
Heading heroTitle;
Paragraph heroCopy;
Button heroButton;
}
pageMain {
width = @pageWidth;
display = "grid";
gap = "16px";
heroTitle {
textContent = "Hello";
}
heroCopy {
textContent = "WEB compiles to HTML and CSS.";
}
heroButton {
textContent = "Launch";
padding = "12px 18px";
}
}
```
## 3. Top-Level Rule Order
The compiler is strict about what may appear at the top of the file.
Recommended order:
1. one optional `define { ... }` block
2. optional top-level global selector blocks with `html { ... }` or `* { ... }`
3. rules and blocks
4. optional top-level `::head` blocks
5. optional top-level `::script` blocks
6. top-level `::keyframes` may appear with other top-level rules, but never inside a block
Hard constraints:
- variables must be declared inside `define { ... }`
- type declarations must be declared inside `define { ... }`
- style inheritance declarations must be declared inside `define { ... }`
- `define { ... }` may appear at most once
- `define { ... }` must appear before rules
- variables cannot use `js\`...\``
- `html { ... }` and `* { ... }` are reserved for global CSS selector blocks
- `::head` must be top-level
- `::script` must be top-level
- `::keyframes` must be top-level
## 4. Core Syntax
### 4.1 `define { ... }`
Syntax:
```web
define {
@space = "1rem";
Button actionButton;
actionButton heroButton;
heroButton extends actionButton;
}
```
What belongs inside `define`:
- variable declarations
- type declarations
- style inheritance declarations
What does not belong inside `define`:
- DOM rules
- CSS property assignments
- `styles { ... }`
- `::pseudo`
- `::media`
- `::attrs`
- `::head`
- `::script`
- `::keyframes`
### 4.2 Type declarations
Syntax:
```web
BaseType NewType;
```
Examples:
```web
Button actionButton;
actionButton heroButton;
Heading2 sectionHeading;
Article featureCard;
```
What this does:
- creates a named type alias
- allows semantic inheritance
- affects HTML tag inference
What this does not do:
- it does not automatically share CSS properties
- use `storeCard extends card;` for CSS inheritance
- it does not create output by itself
Type declarations must live inside the top-level `define { ... }` block.
### 4.3 Style inheritance
Syntax:
```web
derivedName extends baseName;
```
Example:
```web
define {
Article card;
card storeCard;
storeCard extends card;
}
```
What this does:
- copies CSS from `card` into `storeCard`
- keeps HTML tag inference separate from CSS reuse
- supports transitive inheritance such as `featuredStoreCard extends storeCard;`
What this does not do:
- it does not change HTML tag inference by itself
- it does not create output by itself
Important behavior:
- style inheritance is CSS-only
- explicit derived styles override inherited base styles
- closer ancestors override farther ancestors
- circular style inheritance is not allowed
- inheritance applies to normal rules, descendant rules, style scopes, pseudo blocks, media blocks, and `raw`
If you want the derived name to share both:
- the same semantic HTML tag
- and the same CSS
combine type inheritance and style inheritance:
```web
define {
Article card;
card storeCard;
storeCard extends card;
}
```
Style inheritance declarations must live inside the top-level `define { ... }` block.
### 4.4 `::head`
Use `::head { ... }` when you want WEB to emit literal `meta` and `link` tags inside the document head.
Syntax:
```web
::head {
meta {
name = "description";
content = "Landing page built in WEB.";
}
link {
rel = "help";
href = "compiler.md";
type = "text/markdown";
}
}
```
Behavior:
- `::head` is top-level only
- it creates HTML only, not CSS
- it only supports `meta { ... }` and `link { ... }` entries
- each `meta` or `link` entry supports direct HTML attribute assignments only
- attribute names are written in camelCase and compile to kebab-case
- rendered head entries are inserted before ``
### 4.5 `::script`
Use `::script { ... }` when you want WEB to emit a literal script tag.
Syntax:
```web
::script {
src = "/assets/app.js";
defer = "true";
code {
function helloWorld () {
alert("hello world");
}
}
}
```
Behavior:
- `::script` is top-level only
- it creates HTML only, not CSS
- it supports direct HTML attribute assignments
- it supports one optional `code { ... }` block
- the `code { ... }` body is copied as raw script text
- rendered script tags are inserted near the end of ``
Attribute notes:
- `defer = true;` emits a bare boolean attribute
- `defer = "true";` emits `defer="true"`
- camelCase names compile to kebab-case, so `dataMode` becomes `data-mode`
### 4.6 Global selector blocks
WEB has two special global CSS blocks:
```web
* {
boxSizing = "border-box";
}
html {
background = "#101522";
color = "#f7f6ff";
}
```
Behavior:
- these compile directly to `*` and `html` CSS selectors
- they are CSS-only and never create DOM nodes
- they must appear at the top level
- they are also allowed inside a top-level `::media`
- nested `html { ... }` or `* { ... }` inside an element scope is invalid
These are not normal WEB nodes. They bypass tag inference and the document model.
### 4.7 Variables
Syntax:
```web
define {
@name = value;
}
```
Examples:
```web
@pageWidth = "min(1120px, calc(100vw - 48px))";
@panelRadius = "24px";
@borderRule = "1px solid rgba(0, 0, 0, 0.08)";
```
Rules:
- variable names must start with `@`
- variables must be declared inside `define { ... }`
- variables may reference other variables
- variables may not use `js\`...\``
### 4.8 Dot notation
Syntax:
```web
pageMain.heroSection.heroTitle.textContent = "Hello";
pageMain.heroSection.padding = "24px";
```
Meaning:
- the path before the final segment identifies a node
- the final segment is the property name
### 4.9 Nested blocks
Syntax:
```web
pageMain {
heroSection {
heroTitle {
textContent = "Hello";
}
}
}
```
Equivalent to dot notation:
```web
pageMain.heroSection.heroTitle.textContent = "Hello";
```
### 4.10 Dotted block scopes
Also valid:
```web
pageMain.heroSection {
heroTitle {
textContent = "Hello";
}
}
```
### 4.11 Bare identifiers are not valid rules
This is invalid:
```web
pageMain
```
After a path, the parser expects either:
- `=` for an assignment
- `{` for a block
## 5. HTML Structure Model
WEB does not let you write literal HTML tags in normal source. It creates HTML by rebuilding a tree from rule paths.
Example:
```web
pageMain.heroSection.heroTitle.textContent = "Hello";
pageMain.heroSection.heroButton.textContent = "Launch";
```
This produces a DOM tree like:
- `pageMain`
- `heroSection` inside `pageMain`
- `heroTitle` inside `heroSection`
- `heroButton` inside `heroSection`
Important:
- each unique path maps to one element
- later assignments update the same node
- path identity matters more than declaration order
## 6. HTML Tag Inference
The compiler resolves each node name through the type symbol table, then infers an HTML tag from the resolved base type.
### 6.1 Declared names
Example:
```web
Button heroButton;
```
`heroButton` resolves to base type `Button`, so it renders as `