Gotchas

Almost every one traces back to a single fact.

ARKlight parses your entry file as an AST and never runs it to discover routes. It looks for specific syntax shapes, not runtime behavior.

1. The include line is mandatory

Every file using the built-in vocabulary must begin with

# include <stdlib.ARKlight>

. Without it you get

name 'Site' is not defined

. Each imported project module needs its own include line too.

2. Routes need the literal decorator

@site.page("/")
def home():
    ...

site.page("/")(home)

is valid Python but is silently ignored. The build fails with

No pages registered on 'site'

3. Decorators belong in the entry file

Discovery scans only the file you pass to

arklight build

. A decorator inside an imported module is invisible. Keep every

@site.page

in the entry file and import helpers for everything else.

4. State is a child of Page

# Wrong: State is never attached to the page
State("count", 0)
return Page(Text(Bind("count")))

# Right
return Page(
    State("count", 0),
    Text(Bind("count")),
)

Error table

Error	Likely cause
name 'X' is not defined (a component name)	Missing the include line.
No pages registered on 'site'	Decorator used as a call, or placed in an imported module.
state isn't declared on this page	State(...) called as a bare statement instead of a Page child.
PreambleCollisionError	Two includes bind the same name differently, or your code rebinds a preamble name.
BracketIndentationError	A continuation line inside brackets is not indented further than its opener, or nesting is deeper than 8 levels.
ComponentError on a component call	A registered component takes keyword props only.
Build halts on an unresolved link or asset	A Link to a route that does not exist, or a src or favicon not under assets/.
Item can only contain text	A Code or other component placed inside an Item.

For anything else, run

arklight build --debug

to see the full traceback.