gitoria

All repositories: gitoria

Readme Code Pull requests Releases Tickets Settings

Commit4a2d7125

4a2d7125initial commitmre2026-09-25 19:10

4a2d7125/plugins/web/WebFramework.hl

117.8 KB

// The framework's server half — the SERVER REALM's entrypoint, and the EDGE
// MODULE for the carriers the manifest declares.
// Its jobs: answer a URL with the HTML of a constructed component (SSR), ship
// the browser the client, the View tree and the state to continue from, carry
// the boundary in both directions (a websocket on the same port, a POST for a
// peer that has none), and run the server faces an inbound emit names.
import { NativeWebSocketServer, Response, randomToken } from 'hl:http1'
import View from './view.hl'
import Router from './router.hl'
import Sessions from './sessions.hl'
import Session from './session.hl'
// the Style walk — named Css here because `Style` is a well-known MEMBER name
import Css from './css.hl'
import Compile from './compile.hl'
import { readFile, exists, watch } from 'hl:fs'
import { file, env } from 'hl:proc'
import { now } from 'hl:time'
import { newline, tab } from './view.hl'
Hybrid routes = [] // bound by `new WebFrameworkServer(routes = …)`
// THE PROJECT'S STYLES FILE, declared by the app as a property of the framework:
// `new WebFrameworkServer(…, styles = './styles.hl')`. A file of statics and one
// `Style { }` root member (COMPONENTS §4) — the design tokens and the global
// rules, under every component's own Style in the one stylesheet. null: none.
styles = null // the app's styles file: the class it imported, or a path
// WHO AN OUTWARD EVENT IS FOR (creator, 2026-09-12): per event, a function the app
// declares — `audience = { postCreated = (p, session) => … }` — called for every
// connection that has a listener for the event mounted, with the event's
// arguments and that connection's session; a true answer sends the frame. An
// event with no entry reaches the emitting connection only. Only the app knows
// who is entitled; the face stays pure; the framework applies the answer.
Hybrid audience = {}
// THE SESSION STORE (the archive's manifest members, mission 252/255): nothing said →
// `<project>/.sessions`; a path → that path; `false` → memory only. The three clocks
// are seconds; null takes the layer's defaults (14 days valid, 15 min resident, sweep
// every 5 min).
// THE DEV WATCHER (the archive's `watch`): every save under the project arrives as an
// event; a save that changes the analysis re-reads the graph, drops every cache and tells
// every open tab to reload. Off by default — a deploy never re-analyses itself.
Boolean minify = false // production: one-line HTML, compact JavaScript modules
Boolean watchMode = true
lastChange = 0 // epoch ms of the last save acted on (the debounce)
String | Boolean sessionDir = null
Number sessionMaxAge = null
Number sessionIdle = null
Number sweepInterval = null
// THE SESSION COOKIE'S NAME (ticket #10). Cookies ignore the port, so two apps on one
// host that both answered `hlsid` overwrote each other's sessions; an app names its own.
// null: `hlsid`.
String sessionCookie = null
// THE COOKIE'S `Secure` FLAG (ticket #27): true when the app is reached over https —
// behind a TLS proxy the server itself speaks plain http and cannot tell, so the app
// says so. The browser then never sends the session over plain http. false: not set.
Boolean sessionSecure = false
// THE COOKIE'S `Domain` (ticket #44): 'example.org' shares one session with every
// <sub>.example.org, which a host-only cookie cannot. null: host-only, no attribute.
String sessionDomain = null
Number port = 8080
String host = null // the interface to bind; null → HL_HOST/HOST, the manifest's `host`, 0.0.0.0
// THE ONE RUNTIME URL, and the reason it is a member and not a literal in two
// places: a module's `import … from "./hl-runtime.js"` resolves against the
// MODULE's own url, so a server answering modules at two directory depths hands
// the browser two runtime urls — two ES-module instances, two `globalEvents`
// buses, two `__hlRealm` variables, and a crossing emit announced on a bus the
// edge module never taps. Every module this server compiles is handed this one
// specifier (hlJs's third argument).
// THE DIRECTORY THE FRAMEWORK ANSWERS FROM, and the reason it is its own member:
// a package's browser half is served BESIDE THE RUNTIME, and the compiler derives
// that url from the runtime's own (`js_module.zig browserHalfUrl`:
// `<dirname(runtime)>/<pkg>/client.js`). Two sides deriving one url from one
// directory is what keeps the module's `import` and this server's route table
// from drifting apart.
static halfDir = '/__hl'
static runtimeUrl = halfDir + '/hl-runtime.js'
clientUrl = halfUrl('web')
styleUrl = halfDir + '/app.css'
// THE FRAMEWORK'S OWN URLS ARE ROUTES (creator: "just use routes"), appended to
// the app's table with `routes[] = …` — the append that takes on a caller's
// pinned argument during construction, where `routes = routes + […]` is dropped.
// Three of them here — the runtime, the REST carrier and the app's one
// stylesheet — and then one per PACKAGE BROWSER HALF the app's graph holds,
// appended below where the graph is known. There is no catch-all that compiles
// any graph file a url names.
routes[] = { pattern = runtimeUrl framework = true function = (route, req) => {
return new Response(runtime, { headers = { 'Content-Type' = 'text/javascript; charset=utf-8' } })
} }
// THE REST CARRIER, the same emit/ack pair for a peer that cannot hold a socket
// (SPEC: `POST /__hl/emit`).
// ITS SESSION IS THE COOKIE'S (creator, 2026-09-14): this is an HTTP request like
// the page request, so it resolves the SAME session the page route would for that
// cookie — a `session.user` a face writes here is what the next document reads.
// Before this the face was handed null and a login over the fallback was lost.
// AN OUTWARD EMIT RAISED UNDER IT RIDES BACK IN THE ANSWER: there is no
// connection to push to, so the frames a face raised for the CALLER are
// collected while it runs and shipped in the ack as `emits`, which the client
// half delivers before it resolves the emit. The audience fan-out to the other
// connections of that user is the same walk it always was.
routes[] = { pattern = '/__hl/emit' framework = true function = (route, req) => {
if (req.method != 'POST') { return notFound(req.path) }
let s = sessions.resolve(req.headers['cookie'] != null ? req.headers['cookie'] : req.headers['Cookie'])
let fresh = s == null
if (fresh) { s = sessions.mint() }
// the session travels in a MEMBER, not an argument: a call argument is a copy,
// an instance inside it included, and a copied session loses the face's write
postSession = s
postHost = hostOf(req.headers['host'])
let res = new Response(inbound(null, JSON.parse(req.body)), { headers = { 'Content-Type' = 'application/json; charset=utf-8' } })
if (fresh) { res.headers['Set-Cookie'] = sessions.cookieHeader(s.id) }
return res
} }
// THE APP'S ONE STYLESHEET — the `styles` file's rules and every mounted
// component's `Style { }`, walked in style.hl and cached after the first ask.
routes[] = { pattern = styleUrl framework = true function = (route, req) => {
return new Response(stylesheet(), { headers = { 'Content-Type' = 'text/css; charset=utf-8' } })
} }
// THE COMPONENT MODULES ARE ROUTES TOO — the framework's, not the app's: one per
// file a page route mounts and per wrapper above it (the graph's `parent`
// chain), served at the file's own `.hl` url as the browser's projection. A
// browser executes a module by its MIME type, so `text/javascript` at
// `/components/home.hl` is a module, and the url is the path the author wrote.
// Nothing else is served as a module: a file no page route reaches has no url.
// THE LANGUAGE GRAPH, AND THE REALMS ARE THIS PACKAGE'S (creator, 2026-09-12: "the project.hl
// defines no realms so the framework just fills them itself"). This file is the server
// realm's entrypoint, client.hl beside it the browser's; the app reaches both by
// importing hl:web, and the graph follows that reference into the package.
graph = hlProject(
realms = {
server = { entrypoint = './WebFramework.hl' }
client = { entrypoint = './client.hl' }
}
transports = [
['websocket' 'client' 'server']
['websocket' 'server' 'client']
['rest' 'client' 'server']
]
)
gen = graph.analysisGen // the syntax reflection's handle: the routes below read Views
// TWO WEB FRAMEWORKS IN ONE APP IS NOT AN APP (creator, 15 Sep: project.hl switched
// to the other framework the repo had then while styles.hl still said 'hl:web/css').
// Both packages load, both `on server page` faces answer the same navigation, and
// the second answers on a blank instance — a NotCallable deep inside the other framework's dispatch, which
// says nothing about the two import rows that caused it. So it is refused HERE,
// before anything is served, naming both rows.
oneFrameworkOnly()
// A VALUE-FORM EMIT HAS ONE ANSWERER (SPEC "An emit ANSWERS", ticket #20): checked here,
// before anything is served, because the wire does not say which form an emit was
oneAnswererEach()
// THE APP'S SETTINGS come from the file that constructed this one when they were not
// passed (the archive's `configure()`): `styles`, `audience`, `sessionDir`, the clocks,
// `watchMode`, `minify`, `port`
cfg = hlConstructor()
if (cfg != null) {
if (styles == null && cfg.styles != null) { styles = cfg.styles }
if (cfg.audience != null && audience.keys().length == 0) { audience = cfg.audience }
if (sessionDir == null && cfg.sessionDir != null) { sessionDir = cfg.sessionDir }
if (sessionMaxAge == null && cfg.sessionMaxAge != null) { sessionMaxAge = cfg.sessionMaxAge }
if (sessionIdle == null && cfg.sessionIdle != null) { sessionIdle = cfg.sessionIdle }
if (sweepInterval == null && cfg.sweepInterval != null) { sweepInterval = cfg.sweepInterval }
if (sessionCookie == null && cfg.sessionCookie != null) { sessionCookie = cfg.sessionCookie }
if (cfg.sessionSecure != null && sessionSecure == false) { sessionSecure = cfg.sessionSecure }
if (sessionDomain == null && cfg.sessionDomain != null) { sessionDomain = cfg.sessionDomain }
if (cfg.watchMode != null) { watchMode = cfg.watchMode }
if (cfg.minify != null) { minify = cfg.minify }
if (cfg.port != null) { port = cfg.port }
}
served = {}
mounted = []
for (r of routes) { if (r.component != null) { mounted[] = keyOf(r.component) } }
for (k of mounted) {
let key = k
// a file the graph does not hold is refused at its route row, below (servedKeys
// → routeComponentKey: this walk reads the evaluated table, which has no lines)
if (graph.files[key] == null) { key = null }
while (key != null) {
serveComponent(key)
let child = key
key = graph.files[key].parent
// A PARENT IS A COMPONENT (COMPONENTS §5): one without a View wraps nothing, and
// every page under it answered a 500 while the boot said nothing (322 row 13)
if (key != null && viewHandle(key) == 0) {
hlError("hl:web: the `parent` clause of " + child + " names " + key + ", which declares no View: a parent is a component whose View places `slot` where the page renders")
}
}
}
// EVERY PACKAGE'S BROWSER HALF IS SERVED, BY ONE RULE. A package whose browser
// side is written in this language ships it as `client.hl` beside its
// plugin.json; the compiler compiles it like any other file and writes the
// importing module `import { … } from "<halfDir>/<pkg>/client.js"`
// (js_module.zig browserHalf / browserHalfUrl). Something has to answer that url,
// and this is it — for EVERY such package the graph holds, because the rule
// belongs to the language and not to one package. hl:web's own half is the first
// case of it and no longer a hard-coded route of its own; hl:dnd is the second.
//
// The graph is the whole guard: a key is here only because the entry's closure
// REACHED that package's half through an import, which is the same reason a
// component has a module url. A package nothing imports is served nothing.
for (gk of graph.files.keys()) {
if (gk.startsWith('hl:') && gk.endsWith('/client.hl')) { serveHalf(gk) }
}
// ---- WHAT THIS APP SERVES, OFF THE ANALYSIS ALONE (mission 315) ----------------
// These four are STATIC, so they answer with no instance and without constructing
// anything: the compiler evaluates `servedModulesOf(graph)` at BUILD time to bake
// each module's text, and this file's own root uses the very same functions at
// boot. One definition, two callers — a second derivation would drift, and a
// compiled binary would then serve text generated against different urls.
//
// The seed is the entry's route table AS WRITTEN, read through `hlSyntax`, not
// the evaluated `routes` member: evaluating it means constructing the app, and
// constructing this class binds a socket. The graph carries the entry's record
// since 2026-09-16, which is what makes that readable at all.
// A ROUTE'S COMPONENT IS A PAGE: a file without a View answered every request with a 500
// ("declares no View", raised without a span) while the boot said nothing (mission 322
// row 13). Refused at the row instead.
static routePage = (gen, entryKey, valueNode, key) => {
if (!hasViewMember(gen, key)) { hlSourceError(gen, entryKey, valueNode, key + " declares no View, so it is no page: a route's component is a file whose View renders") }
return key
}
// The key a route row's `component` names: an imported class, or a path string.
// Anything else is a located refusal AT THE ROW — never silently unserved.
static routeComponentKey = (graph, gen, entryKey, imports, valueNode) => {
let v = hlSyntax(gen, entryKey, valueNode)
if (v == null) { return null }
if (v.tag == 'literal' && v.kind == 'string') {
let t = v.text
let k = t.startsWith('./') ? t.slice(2) : t
// A PATH NO FILE OF THE APP IMPORTS IS NOT IN THE GRAPH: the analysis never read
// it, so nothing can be served for it — refused here, at the row, instead of a
// null deep in the framework once the server is already up (STATUS §2 item 0)
if (graph.files[k] == null) { hlSourceError(gen, entryKey, valueNode, "the app never imports " + t + ", so the analysis never read it and the app would serve no module for it: import it in this file (`import Page from '" + t + "'`) and write `component = Page`") }
return routePage(gen, entryKey, valueNode, k)
}
if (v.tag == 'identifier') {
for (imp of imports) {
if (imp.default == v.name && imp.key != null) { return routePage(gen, entryKey, valueNode, imp.key) }
}
}
hlSourceError(gen, entryKey, valueNode, "a route's component must be an imported component class or a path string — this one the analysis cannot resolve to a file, so the app would serve no module for it")
return null
}
// does the file at `key` declare a View? (a component, as opposed to a plain class)
static hasViewMember = (gen, key) => {
for (m of hlMembers(gen, key)) {
if (m.name == 'View') { return true }
}
return false
}
// `key` and every component it composes, once each — the same walk
// `serveComponent` performs, as a function of the graph.
static collectServed = (graph, gen, out, key) => {
if (key == null || graph.files[key] == null) { return null }
for (k of out) { if (k == key) { return null } }
out[] = key
for (imp of graph.files[key].imports) {
if (imp.default != null && imp.key != null && hasViewMember(gen, imp.key)) {
collectServed(graph, gen, out, imp.key)
}
}
return null
}
// Every key this app answers a module for: each route's component and the wrapper
// chain above it, the components those compose, and every package's browser half.
static servedKeys = (graph) => {
let gen = graph.analysisGen
let entryKey = graph.manifest.file
let out = []
if (entryKey != null && graph.files[entryKey] != null) {
let imports = graph.files[entryKey].imports
let routesNode = 0
for (m of hlMembers(gen, entryKey)) {
if (m.name == 'routes') { routesNode = m.node }
}
if (routesNode != 0) {
let arr = hlSyntax(gen, entryKey, routesNode)
if (arr != null && arr.tag == 'array_expression') {
for (e of arr.elements) {
let row = hlSyntax(gen, entryKey, e)
if (row != null && row.tag == 'object_expression') {
for (pe of row.entries) {
let prop = hlSyntax(gen, entryKey, pe)
if (prop != null && prop.tag == 'object_property' && prop.key == 'component') {
let key = routeComponentKey(graph, gen, entryKey, imports, prop.value)
// the wrapper chain above it, deepest last — a page is
// served inside whatever wraps it
let k = key
while (k != null) {
collectServed(graph, gen, out, k)
k = graph.files[k] != null ? graph.files[k].parent : null
}
}
}
}
}
}
}
}
return out
}
// EVERY PACKAGE'S BROWSER HALF, BY ONE RULE — a package whose browser side is
// written in this language ships it as `client.hl`, the compiler writes
// `<halfDir>/<pkg>/client.js` into every importing module, and something has to
// answer that url. The graph is the whole guard: a key is here only because the
// entry's closure reached that package.
//
// SEPARATE FROM `servedKeys` ON PURPOSE: a half gets a ROUTE but is not a module
// url of this app, so it is not in the map `hlJs` is handed. That asymmetry is
// the existing `serveHalf`/`serveComponent` split, stated rather than inherited
// by accident — measured 2026-09-16, when folding the two together made the
// analysis set one key wider than the route walk's.
static packageHalfKeys = (graph) => {
let out = []
for (gk of graph.files.keys()) {
if (gk.startsWith('hl:') && gk.endsWith('/client.hl')) { out[] = gk }
}
return out
}
// The browser realm's NAME, off the graph — the declared realm whose entrypoint
// is this framework's client half. Static, so the compiler can ask it too.
static clientRealmOf = (graph) => {
for (name of graph.realms.keys()) {
if (graph.realms[name].entrypoint == 'hl:web/client.hl') { return name }
}
return null
}
// EVERY MODULE THIS APP SERVES, COMPILED — what a native binary answers `hlJs`
// with (mission 315). The emitter needs the runtime specifier, the browser
// realm and the served-url map; all three are functions of the analysis, so the
// whole map is, and the COMPILER can build it without an instance.
//
// `minify` is NOT: it is an app setting bound at construction, and the analysis
// cannot evaluate a construction. The value used is recorded beside each
// module so a binary asked for a different one refuses at the call instead of
// answering text generated the other way.
// HOW THE APP ASKED FOR ITS MODULES. A build bakes ONE form of every module and
// a binary answering the other form would be different bytes, so the build must
// read the app's own answer — and the app writes it where it configures the
// framework: `new WebFramework(… minify = true …)` in the manifest. The analysis
// carries a construction's named arguments, so this is a READ of the same syntax
// `servedKeys` reads for the routes, not a second declaration.
//
// A COMPUTED `minify` IS NOT READ HERE, and nothing is guessed from it: a build
// cannot evaluate an expression the running app has not reached yet. Such an app
// bakes the unminified form, exactly as every app did before this, and if it
// then asks for the other form at run time the binary says so at the request —
// "this binary carries the module compiled the other way", located, which is
// the refusal that already exists and the one measured on the creator's social
// app (2026-09-17). Writing the literal in the manifest is what removes it.
static manifestMinify = (graph) => {
let gen = graph.analysisGen
let key = graph.manifest.file
if (key == null || graph.files[key] == null) { return false }
for (m of hlMembers(gen, key)) {
let s = hlSyntax(gen, key, m.node)
if (s != null && s.tag == 'new_expression' && s.named != null) {
for (h of s.named) {
let p = hlSyntax(gen, key, h)
if (p != null && p.tag == 'object_property' && p.key == 'minify') {
let v = hlSyntax(gen, key, p.value)
if (v != null && v.tag == 'literal' && v.kind == 'boolean') { return v.text == 'true' }
}
}
}
}
return false
}
static bakeModules = (graph) => {
let realm = clientRealmOf(graph)
let served = servedModulesOf(graph)
let min = manifestMinify(graph)
let out = {}
for (k of servedKeys(graph)) {
if (graph.files[k] != null) {
let p = graph.files[k].path
out[p] = {
text = hlJs(p, min, runtimeUrl, realm, served)
minify = min
runtime = runtimeUrl
realm = realm
}
}
}
// EVERY PACKAGE HALF TOO. The root walk above serves `<halfDir>/<pkg>/client.js`
// for every `hl:<pkg>/client.hl` the graph holds, and a compiled binary answers
// from BAKED text alone — so a bake that skipped them served the page and then
// 404'd on the module the page imports, leaving the client half of the app
// dead with nothing reported (measured on projects/framework, 2026-09-16).
// Same rule, same list, one loop later: what the server routes, the build bakes.
for (gk of graph.files.keys()) {
if (gk.startsWith('hl:') && gk.endsWith('/client.hl') && graph.files[gk] != null) {
let hp = graph.files[gk].path
if (out[hp] == null) {
out[hp] = {
text = hlJs(hp, min, runtimeUrl, realm, served)
minify = min
runtime = runtimeUrl
realm = realm
}
}
}
}
return out
}
// file path → the url this server answers its module at. What `hlJs` is handed,
// and what the compiler bakes against.
static servedModulesOf = (graph) => {
let out = {}
for (k of servedKeys(graph)) {
if (graph.files[k] != null) { out[graph.files[k].path] = '/' + k }
}
return out
}
// ONE PACKAGE HALF'S ROUTE. It is a FUNCTION and not the body of the loop above
// because the url's route closure must hold THIS key: a `let` in a loop body is
// one binding the closures share, so every route built that way would serve the
// last package's half (measured 2026-09-14 — both /__hl/web/client.js and
// /__hl/dnd/client.js answered with hl:web's module). A parameter is a fresh
// binding per call, which is the same reason serveComponent below is a function.
serveHalf(key) {
routes[] = { pattern = halfUrl(key.slice(3, key.length - 10)) framework = true function = (route, req) => { return serveHl('/' + key) } }
return null
}
// a mounted file's module route, and the routes of the components it composes
// (an import with a View), recursively — off the graph, once each
serveComponent(key) {
if (served[key] != null) { return null }
served[key] = true
routes[] = { pattern = moduleUrl(key) framework = true function = (route, req) => { return serveHl(req.path) } }
for (imp of graph.files[key].imports) {
if (imp.default != null && imp.key != null && viewHandle(imp.key) != 0) { serveComponent(imp.key) }
}
return null
}
// THE PROJECT DIRECTORY: this file lives in a package, so the app's directory is read
// off a file that is the app's — the first route component's key against its path
root = projectRoot()
view = new View
css = new Css(minify = minify, view = view)
compiler = new Compile
sessions = new Sessions(dir = sessionDirPath(), maxAge = sessionMaxAge != null ? sessionMaxAge : 1209600, idle = sessionIdle != null ? sessionIdle : 900, sweepEvery = sweepInterval != null ? sweepInterval : 300, cookie = cookieName(), secure = sessionSecure, domain = sessionDomain != null ? sessionDomain : '')
sessions.open()
// THE STYLES FILE IS NAMED AT BOOT, not at the first request for the stylesheet: a value
// that names no file, or a file the graph does not hold, is the app's mistake and the
// app does not start with it (ticket #12)
if (styles != null) {
if (hlTypeName(styles) != 'String' && hlTypeName(styles) != 'Class') { refuseAtSetting('styles', "hl:web: styles is the styles file — the class the app imported (`styles = Styles`) or a path string ('./styles.hl') — and this one is a " + hlTypeName(styles)) }
if (graph.files[keyOf(styles)] == null) { refuseAtSetting('styles', "hl:web: styles names " + keyOf(styles) + ", which is not in the project graph — import it from the app's entry (`import Styles from './styles.hl'`) and write `styles = Styles`") }
}
// the whole tree, nothing excluded: dot directories (the session store) are skipped by
// the walker's own rule, and a custom store inside the tree is the app's choice to pay for
if (watchMode) { __native("eventloop.register", watch(root), "hlFileChanged") }
sheetText = null // the stylesheet, walked once at the first request for it
router = new Router(routes = routes)
trees = {} // key → the View tree, built once
slotAt = {} // key → where its View places its one `slot`
styleNames = {} // key → the rule names of the file's Style, off the syntax
styleRefs = {} // key → [{ tag rule }] the View wrote
styleTags = {} // key → the element names this file's View renders
styleIds = {} // key → the literal `id` values this file's View writes (R3)
staticHolders = {} // key → an instance of a file whose statics another file imports
modules = {} // key → the browser module (JavaScript text), compiled once at boot
servedUrls = null // file path → the url this server answers its module at, for hlJs
runtime = hlJsRuntime() // the runtime library every module imports as "./hl-runtime.js"
peers = {} // connection key → the WsClient, while it is open
peerSession = {} // connection key → its session, from the tab's `hello` (null = anonymous)
peerHost = {} // connection key → the host its upgrade request named (null = none sent)
peerMounts = {} // connection key → the component keys the tab has mounted
// SESSIONS (web/sessions.hl): named by the cookie, at the page request and at the
// socket's handshake alike. Nothing about a session ever reaches page script.
sending = null // the WsClient whose inbound emit is being handled — the peer
// an outward emit reaches, and null under the POST fallback
// THE POST FALLBACK'S PEER IS ITS OWN ANSWER. While a face dispatched over
// `POST /__hl/emit` runs, `posting` is true and every outward emit meant for the
// CALLER is appended here instead of pushed; `inbound` ships the list in the ack.
Boolean posting = false
postEmits = []
postSession = null // the cookie's session of the POST being dispatched
postHost = null // the host of the POST being dispatched
faceHost = null // the host of the carrier whose inbound emit is being dispatched
// ONE PORT, TWO CARRIERS. hl:http1's WebSocket engine answers the Upgrade
// inline on the port this server already bound, so `websocket` and `rest` are
// the same listener — which is why the manifest can declare both for the same
// direction and this file needs no second server.
// EVERY VIEW IS BUILT AT BOOT, not at the first request for its route: a View that
// reads a name its file declares nowhere (checkRead) is the app's mistake, and the
// app does not start with it — the port is bound on the line below this pass.
// THE TWO DERIVATIONS MUST AGREE (mission 315). `served` is built above from the
// EVALUATED route table; `servedKeys(graph)` derives the same set from the
// analysis alone, and the compiler bakes each module's text against the second.
// If they ever disagree the binary would serve modules generated against urls
// this server does not answer, so the disagreement is a refusal, here, at boot.
for (k of servedKeys(graph)) {
if (served[k] == null) {
hlError('hl:web: the analysis says this app serves ' + k + ', the route walk did not — the two derivations of the served set disagree')
}
}
for (k of served.keys()) {
let seen = false
for (a of servedKeys(graph)) { if (a == k) { seen = true } }
if (seen == false) {
let why = ''
for (imp of graph.files[k] != null ? [] : []) { why = why }
hlError('hl:web: the route walk serves ' + k + ', the analysis did not — the two derivations of the served set disagree')
}
}
for (k of served.keys()) { if (viewHandle(k) != 0) { tree(k) } }
// A COMPONENT-REFERENCE CYCLE IS REFUSED HERE (COMPONENTS §12): a View that renders
// itself, directly or through another, is a mount that never ends — it overflowed the
// stack at the first request and the server died of a segfault with nothing said
// (mission 322 row 1).
acyclic = {}
for (k of served.keys()) { if (viewHandle(k) != 0) { referenceCycle(k, []) } }
// …and a page a shell wraps is placed at the shell's slot, inside its body: a page whose
// root is `body` there emitted a second, nested <body> (mission 322 row 5)
for (k of mounted) {
if (graph.files[k] != null && graph.files[k].parent != null && viewHandle(k) != 0 && bodyRooted(k)) {
hlError("hl:web: " + k + " is wrapped by " + graph.files[k].parent + " (its `parent` clause), but its View's root is `body { … }`, the page's body: the shell owns the body, so write the page's root as an element (`main { … }`, `section { … }`)")
}
}
// THE SHEET IS WALKED AT BOOT, so the rules it drops are listed at boot (COMPONENTS §4,
// css.hl's own header): walked at the first request for it, a dead rule was listed only
// once some browser had asked, and a boot log said nothing (mission 322 row 11)
stylesheet()
// EVERY SERVED MODULE IS COMPILED AT BOOT: a free name in a View handler is a located
// compile error (COMPONENTS §6b), and compiled at the first request for the module it
// was a 500 behind a page that had already answered 200 (mission 322 row 14)
for (k of served.keys()) { module(k) }
// THE INTERFACE IS THE OPERATOR'S (ticket #24), on the ladder graph.zig's OperatorBind
// states: the constructor's `host` > HL_HOST (the binary fills it from HOST) > the
// manifest's > 0.0.0.0. Binding the default regardless put an app meant to sit behind
// a proxy on every interface of the machine.
if (host == null) { host = env('HL_HOST') }
if (host == null && cfg != null && cfg.host != null) { host = cfg.host }
if (host == null) { host = '0.0.0.0' }
http = new NativeWebSocketServer(port = port, host = host)
echo 'framework listening on ' + port
module('web/client.hl')
// ---- the browser's modules: compiled IN PROCESS, served from memory --------------
// The JavaScript target is this binary's own function (hlJs), the same one `--js`
// runs from the command line. No child process, no build directory.
//
// THE CLIENT is compiled at boot — every page needs it, and it carries the View
// and the Router with it (one module, three classes). A COMPONENT is compiled ON
// DEMAND, at the request for its own `.hl` url, and kept: a route nobody visits
// costs nothing, and the browser asks for a component's module the first time it
// mounts one.
//
// THE TABLE THE EMITTER WRITES IS DROPPED. `hlJs` puts each file's members,
// handlers and methods — every node of every initializer, with the names it reads —
// into the module, because the old hl:web's browser half reduces that table on every boot.
// This framework asked the same questions at COMPILE time and wrote the answers into
// the component's own statements, so the table is dead weight in the page: 58 KB of
// syntax on the reference app's home page alone. What the framework SERVES is its own
// text, so it leaves that statement out; the language is not asked to change, and
// The old hl:web kept its table untouched.
withoutTables(text) {
// one per FILE the module carries — the client half bundles three classes
let out = text
let at = out.indexOf('hlTablesDef(')
while (at >= 0) {
let end = out.indexOf(');', at)
if (end < 0) { return out }
out = out.slice(0, at) + out.slice(end + 2)
at = out.indexOf('hlTablesDef(')
}
return out
}
// THE APP RUNS ON ONE WEB FRAMEWORK. Which packages are frameworks is READ OFF THE
// GRAPH and not off a list this file keeps: a package the app's entry reached that
// holds a `WebFramework.hl` is one. hl:dnd, hl:http1 and every other package an app
// imports hold none and are untouched by this.
//
// The refusal names the ROW of each import, because the mistake IS an import line —
// a sub-file import (`'hl:web/css'`) counts as much as the package itself, which is
// exactly the case that made it: a lone braced import of a stylesheet helper puts the
// whole package into the graph, and with it a second navigation face.
oneFrameworkOnly() {
let frameworks = {}
for (gk of graph.files.keys()) {
if (gk.startsWith('hl:') && gk.endsWith('/WebFramework.hl')) { frameworks[gk.slice(0, gk.length - 16)] = true }
}
if (frameworks.keys().length < 2) { return null }
// the first row of the app's OWN files that reached each package
let sites = {}
for (k of graph.files.keys()) {
if (!k.startsWith('hl:')) {
for (imp of graph.files[k].imports) {
for (pkg of frameworks.keys()) {
if (sites[pkg] == null && (imp.source == pkg || imp.source.startsWith(pkg + '/'))) {
sites[pkg] = { key = k; node = imp.node; where = k + ':' + imp.line + ':' + imp.col + " imports '" + imp.source + "'" }
}
}
}
}
}
let said = ''
for (pkg of frameworks.keys()) {
if (said != '') { said = said + ', and ' }
if (sites[pkg] == null) { said = said + "'" + pkg + "' (reached through a package, not from a file of the app)" }
else { said = said + sites[pkg].where }
}
let msg = 'this app imports TWO web frameworks: ' + said + '. Both packages load, both answer a page navigation, and the second one answers on a blank instance. An app runs on ONE of them — switch EVERY hl: import in EVERY file of the app to the same package, a sub-file import like \'/css\' included. Switching one line is not switching the app.'
// THE CARET GOES ON ONE OF THE ROWS, and the sentence names them all: two
// import lines are equally the mistake, and a diagnostic can only underline one.
for (pkg of frameworks.keys()) {
if (sites[pkg] != null) { hlSourceError(gen, sites[pkg].key, sites[pkg].node, msg) }
}
hlError(msg)
return null
}
// ONE ANSWERER PER VALUE-FORM EMIT. SPEC: "if more than one class in the destination
// realm declares a non-tap handler for the event, the VALUE form is refused at the emit
// site naming both. As a statement it stays a broadcast and every handler still fires."
// The statement form is what `inbound` does — every face runs. The value form cannot be
// told apart on the wire, so every `x = emit server ev()` the app's files hold is read
// off the analysis here, and one whose event two files answer is refused at its site,
// naming both, before anything is served. Until ticket #20 both faces ran and the first
// answer was taken in silence.
oneAnswererEach() {
let realm = serverRealm()
for (k of graph.files.keys()) {
if (!k.startsWith('hl:')) {
for (e of hlEvents(gen, k).emits) {
if (e.value == true && e.realm == realm) {
let owners = facesOf(e.event)
if (owners.length > 1) {
let named = ''
for (o of owners) { named = named == '' ? o : named + ' and ' + o }
let msg = "hl:web: " + k + ':' + e.line + ':' + e.col + " — this emit waits for the answer of '" + e.event + "', and " + owners.length + " files answer it in the '" + realm + "' realm: " + named + ". A value-form emit has ONE answerer — rename the event in one of them, or emit it as a statement (a broadcast every handler receives)"
hlSourceError(gen, k, e.node, msg)
hlError(msg)
}
}
}
}
}
return null
}
// WHAT THIS SERVER SERVES AS A MODULE OF ITS OWN, by the file's path (mission 314
// rule 0). Handed to `hlJs`, it is what turns `import PostCard from './post_card.hl'`
// into an ES import of `/components/post_card.hl` instead of PostCard's whole class
// text copied into the importing module — EditHistory's class shipped three times on
// the social demo's home page before this. The urls are THIS file's (`moduleUrl`);
// the compiler invents none, and a file this server does not answer for is inlined
// exactly as it always was.
servedModules() {
if (servedUrls == null) {
let out = {}
for (k of served.keys()) { out[pathOf(k)] = moduleUrl(k) }
servedUrls = out
}
return servedUrls
}
// A key the graph holds no file for is answered `null`, and the caller makes
// that a 404: a file the entry's closure never referenced is not part of this
// app, which is what keeps this from being a read of any path a url asks for.
module(key) {
if (modules[key] == null) {
let f = graph.files[key]
if (f == null) { return null }
// THE BROWSER GETS THE BROWSER'S PROJECTION, and nothing else. hlJs's
// fourth argument is the realm the module is produced for: a handler
// written `on server …` is not emitted at all, and a member whose
// initializer reaches a name the browser does not have is declared
// without one, for this server to lay over the instance with the state
// it already ships. The realm NAME comes off the manifest (clientRealm()
// above), never a literal — a project names its own realms.
let text = hlJs(f.path, minify, runtimeUrl, clientRealm(), servedModules())
// AND THE COMPILE STEP'S OWN OUTPUT BESIDE IT (mission 313): a component with a
// View carries, after its class, the paint statements this framework compiled
// from that View — one per bound spot, with its read written in (compile.hl).
// The browser calls them instead of walking the tree at paint time. Text
// produced here and served from memory like the module itself; nothing is
// written to disk and no JavaScript file lives under plugins/.
text = withoutTables(text)
if (viewHandle(key) != 0) { text = text + newline + compiler.module(gen, key, tree(key)) }
modules[key] = text
}
return modules[key]
}
// the file the graph knows under this key — the graph carries every file's own path
pathOf(key) {
let f = graph.files[key]
if (f == null) { hlError('the graph holds no file ' + key + ' — nothing referenced it from the entry') }
return f.path
}
// THE BROWSER'S REALM, off the manifest: the realm whose declared entrypoint is
// this framework's client half. The framework's own two files ARE the two
// realms' entrypoints, so this is a lookup and never a guess.
clientRealm() {
for (name of graph.realms.keys()) {
if (graph.realms[name].entrypoint == 'hl:web/client.hl') { return name }
}
hlError('the manifest declares no realm whose entrypoint is ./client.hl — the browser half of this framework IS a realm, and a page cannot say which realm it is running in until the manifest names it')
}
// THIS realm, off the graph: the declared realm whose entrypoint REACHES this
// file (the app's entry imports it). A face names it, and so does the refusal
// when nothing answers.
serverRealm() {
let mine = graph.files['hl:web/WebFramework.hl'].realms
if (mine.length == 1) { return mine[0] }
hlError('the manifest declares no realm whose entrypoint reaches hl:web/WebFramework.hl — this file cannot dispatch a face without knowing which realm it is')
}
// the app's directory: a route component is the app's file, its key project-relative
projectRoot() {
for (r of routes) {
if (r.component != null) { return rootOf(keyOf(r.component)) }
}
// AN APP OF FUNCTION ROUTES ONLY (ticket #19) has no component to read it off, and
// needs no other: the manifest is the app's file too, and the graph knows its key
if (graph.manifest.file != null && graph.files[graph.manifest.file] != null) { return rootOf(graph.manifest.file) }
hlError('hl:web: the route table names no component and the graph names no manifest file, so the app\'s directory cannot be read off either')
}
// a project-relative key against its absolute path: what is left is the project's directory
rootOf(key) {
let path = pathOf(key)
// A COMPILED BINARY'S PATH IS ITS KEY (mission 318): it carries no
// build directory, so the file's path and its key are the same
// string and the root is the process's own directory. The
// interpreter's path is the script's absolute one, and the key is
// its tail — the root is what stands before it.
if (path == key) { return '.' }
return path.slice(0, path.length - key.length - 1)
}
// THE KEY OF A FILE THE APP NAMED — as the class it imported (`component = SortList`,
// `styles = Styles`: the import is the guarantee the graph reached it) or as a path
// ('./components/home.hl'). A class knows its file (`file(cls)`), and the graph knows
// the file's key.
keyOf(named) {
if (hlTypeName(named) == 'Class') {
let path = file(named)
for (k of graph.files.keys()) {
if (graph.files[k].path == path) { return k }
}
hlError('hl:web: the class at ' + path + ' is not in the project graph — import it from the app\'s entry')
}
// ANYTHING ELSE NAMES NO FILE (ticket #12): `styles = {}` booted and every request
// for the stylesheet was then a NotCallable on this line, with no line of the app's
if (hlTypeName(named) != 'String') { hlError("hl:web: a file the app names — a route's component, or `styles` — is the class it imported or a path string ('./styles.hl'), and this one is a " + hlTypeName(named)) }
if (named.startsWith('./')) { return named.slice(2) }
return named
}
// ---- the View tree: the member's syntax, reflected into plain hybrids ----------
viewHandle(key) {
for (m of hlMembers(gen, key)) {
if (m.name == 'View') { return m.node }
}
return 0
}
tree(key) {
if (trees[key] != null) { return trees[key] }
let handle = viewHandle(key)
if (handle == 0) { hlError('component ' + key + ' declares no View') }
let v = hlSyntax(gen, key, handle)
let nodes = []
for (h of v.entries) {
let n = node(key, h, [], false, [])
if (n != null) { nodes.push(n) }
}
trees[key] = nodes
return nodes
}
// one entry of a hybrid literal → a tree node (null for an attribute: the
// element that owns it reads it)
node(key, handle, path, inFor, rows) {
let n = hlSyntax(gen, key, handle)
if (n == null) { return null }
if (n.tag == 'object_property') {
let v = hlSyntax(gen, key, n.value)
if (v.tag == 'object_expression') {
let childKey = componentKeyOf(key, n.key)
if (childKey != null) { return component(key, n.key, childKey, v, v, path, inFor, rows) }
return element(key, n.key, v, path, inFor, rows)
}
return null
}
if (n.tag == 'literal') { return { k = 'text'; text = n.text; kind = n.kind; } }
if (n.tag == 'identifier') {
// A BARE CAPITALISED REFERENCE IS A COMPOSITION WITH AN EMPTY FILL (§12:
// "`Name { }` is the same reference as bare `Name`"). It is not a read, so it
// is answered before the read rules below refuse the name.
let bareKey = componentKeyOf(key, n.name)
if (bareKey != null) { return component(key, n.name, bareKey, null, n, path, inFor, rows) }
if (n.name == 'slot' || n.name == '$slot') { oneSlot(key, n) }
// AN IMPORTED STATIC IN A VIEW IS FOLDED (the archive did the same at build):
// `h1 { siteTitle }` with `import { siteTitle } from '../store.hl'` is not a
// member of this class, it is a constant of another file — read off that
// file's class once, here, and written into the tree as text
return nameRead(key, n.name, rows, n)
}
if (n.tag == 'view_for') {
// `for (row of list) { … }` — the list is a member (or a row field), the
// body's entries are rendered once per entry with `row` bound to it
let body = hlSyntax(gen, key, n.body)
let children = []
// THE ROW VARIABLE IS IN SCOPE INSIDE THE BODY, and nowhere else: the list is
// read in the scope that stands around the `for`
let list = ref(key, n.list, rows)
let inner = rows.slice(0)
inner.push(n.varName)
for (h of body.entries) {
let c = node(key, h, path, true, inner)
if (c != null) { children.push(c) }
}
// THE SITE, as every element node carries one: the id the module's tables
// file this `for`'s row under, so the browser reads what the list depends
// on from the compiler instead of guessing it off `list.name`.
return { k = 'for'; row = n.varName; list = list; body = children; site = baseName(pathOf(key)) + ':' + n.line + ':' + n.col; }
}
if (n.tag == 'view_if') {
let then = []
let cons = hlSyntax(gen, key, n.consequent)
for (h of cons.entries) {
let c = node(key, h, path, inFor, rows)
if (c != null) { then.push(c) }
}
let other = []
let alt = hlSyntax(gen, key, n.alternate) // null when there is no else
if (alt != null) {
if (alt.tag == 'view_if') {
other.push(node(key, n.alternate, path, inFor, rows))
} else {
for (h of alt.entries) {
let c = node(key, h, path, inFor, rows)
if (c != null) { other.push(c) }
}
}
}
// A BRANCH CONDITION IS A READ (COMPONENTS: a member, a $hole or a loop path).
// Anything else came back null here and the branch rendered nothing, on the
// server and after hydration, with no word said (ticket #17: `if (!flag)`).
let cond = ref(key, n.condition, rows)
if (cond == null) {
let c = hlSyntax(gen, key, n.condition)
hlError("hl:web: " + baseName(pathOf(key)) + ':' + c.line + ':' + c.col + " — a View `if` takes a member, a field path or a `for` row variable as its condition, and this one is an expression: declare it at the root of " + baseName(pathOf(key)) + " (`showIt = !flag`) and write `if (showIt)`")
}
return { k = 'if'; cond = cond; then = then; other = other; site = baseName(pathOf(key)) + ':' + n.line + ':' + n.col; }
}
if (n.tag == 'member_expression') {
// `p.title` — a field path off a member or a row variable
let r = ref(key, handle, rows)
if (r != null) { return r }
}
if (n.tag == 'on_statement') {
// a DOM event handled by the literal that carries it: the browser finds the
// literal in the instance's View by the path of keys and fires the event at it
// THE SITE IS THE HANDLER'S ID: the tables file this handler's write set
// under it, and the browser repaints exactly those members when it runs.
return { k = 'on'; event = n.event; site = baseName(pathOf(key)) + ':' + n.line + ':' + n.col; }
}
return { k = 'other'; tag = n.tag; }
}
// A COMPONENT HAS EXACTLY ONE SLOT (COMPONENTS §2 table, §12): a second one rendered the
// child a second time, with no word said (mission 322 row 4)
oneSlot(key, n) {
let here = baseName(pathOf(key)) + ':' + n.line + ':' + n.col
if (slotAt[key] != null) {
hlError("hl:web: " + here + " — a second `slot` in this View (the first is at " + slotAt[key] + "): a component has exactly one slot, where the page it wraps or the fill it is given renders")
}
slotAt[key] = here
return null
}
isMember(key, name) {
for (m of hlMembers(gen, key)) { if (m.name == name) { return true } }
return false
}
// THE READ OF A BARE NAME IN A VIEW — wherever the name stands. A text child, an
// attribute's value and a reference-site binding are ONE lookup with ONE refusal:
//
// a `for` row variable standing around the read → read at render, from the row
// a member of this file → read at render, from the instance
// a name this file imports by BRACE → a STATIC of another file:
// constant-folded here, at build
// anything else → the located refusal (checkRead)
//
// An ATTRIBUTE used to skip the middle two and record every name as a member read,
// so `a { href = brandHref }` on a braced import asked the instance for a member it
// does not have and the renderer raised error.UndefinedProperty with view.hl's line
// and nothing of the app's — while the same name as a TEXT CHILD rendered fine
// (creator, routger migration W8). A read is a read; where it stands decides
// nothing about what it names.
nameRead(key, name, rows, at) {
if (rows != null && rows.includes(name)) { return { k = 'member'; name = name; } }
if (isMember(key, name)) { return { k = 'member'; name = name; } }
// A BRACED IMPORT FOLDS EVEN WHEN ITS VALUE IS NULL: the name resolved, so the
// read is answered here and never reaches the instance (a null static used to
// fall through to a member read and raise the same UndefinedProperty).
if (importsName(key, name)) {
let folded = importedStatic(key, name)
// THE VALUE AS WELL AS THE TEXT: an attribute and a text child want the text,
// and a reference binding wants the value the author's file declared (§12)
return { k = 'text'; text = folded == null ? '' : '' + folded; kind = 'folded'; value = folded; }
}
checkRead(key, name, rows, at)
return { k = 'member'; name = name; }
}
// A VIEW READS ONLY WHAT ITS FILE DECLARES. A name that is neither a member of
// this class, nor a static it imports by brace, nor a `for` row variable standing
// around this read, is a typo or a missing declaration — refused HERE, at the
// build of the tree (boot), naming the file and the line, instead of a 500 out of
// the renderer with the language's UndefinedProperty and no line of the app's.
checkRead(key, name, rows, n) {
if (rows != null && rows.includes(name)) { return null }
if (isMember(key, name)) { return null }
if (importsName(key, name)) { return null }
let hint = name == 'session' ? "`session = null` to receive the connection's session" : name == 'host' ? "`host = null` to receive the request's host" : "`" + name + " = null`"
hlError("hl:web: " + baseName(pathOf(key)) + ':' + n.line + ':' + n.col + " — the View reads '" + name + "', which this file declares nowhere: declare it at the file's root (" + hint + "), or write the name it was meant to be")
}
// does this file import that name by brace from another file?
importsName(key, name) {
for (imp of graph.files[key].imports) {
if (imp.key != null && imp.names.includes(name)) { return true }
}
return false
}
// the value of a static this file imports by brace from another .hl file, or null —
// read off an instance of that file (a class value takes no computed index, an
// instance does; the file is constructed once, its statics were evaluated at load)
importedStatic(key, name) {
for (imp of graph.files[key].imports) {
if (imp.key != null && imp.names.includes(name)) {
if (staticHolders[imp.key] == null) { staticHolders[imp.key] = construct(imp.key, constructionArgs(imp.key, {}, anonSession(), null)) }
return staticHolders[imp.key][name]
}
}
return null
}
// a READ in the View: a member (`title`), or a field path (`p.title`) whose root
// is a member or a `for` row variable — the client decides which at render time
ref(key, handle, rows) {
let n = hlSyntax(gen, key, handle)
if (n.tag == 'identifier') { checkRead(key, n.name, rows, n) return { k = 'member'; name = n.name; } }
if (n.tag == 'member_expression' && !n.computed) {
let obj = hlSyntax(gen, key, n.object)
let prop = hlSyntax(gen, key, n.property)
if (obj.tag == 'identifier') { checkRead(key, obj.name, rows, obj) return { k = 'field'; name = obj.name; path = [prop.name]; } }
let inner = ref(key, n.object, rows)
if (inner != null && inner.k == 'field') {
let path = inner.path.slice(0)
path.push(prop.name)
return { k = 'field'; name = inner.name; path = path; }
}
}
return null
}
// THE COMPOSED CHILD: an entry named after a class the file imports, whose file
// has a View. `Child { count = count on done(v) { … } }` — the entries are the
// BINDINGS (host values handed to the child's construction as named arguments)
// and the reference-site handlers. The graph says which name is which file.
componentKeyOf(key, name) {
for (imp of graph.files[key].imports) {
if (imp.default == name && imp.key != null && viewHandle(imp.key) != 0) { return imp.key }
}
return null
}
// THE REFERENCE'S SITE IS IN ITS PATH. A path of class names alone made two
// references of one class under one parent (`body/Card` twice) the SAME node key,
// so both collapsed onto one mount and one of the two fills was lost. A reference
// is a construction: each one is its own mount, so each one is its own path.
componentStep(cls, at) {
return cls + '@' + at.line + ':' + at.col
}
// is this entry a `Style.rule` reference? (the `Style` of THIS file, by name)
styleRef(key, e) {
let obj = hlSyntax(gen, key, e.object)
return obj.tag == 'identifier' && obj.name == 'Style'
}
// THE REFERENCE'S POSITIONAL SIGNATURE (§12: "a reference is a construction, so its
// POSITIONAL entries bind to the class's declared properties in declaration order —
// the same rule `new X(a, b)` follows").
//
// MEASURED, not guessed (2026-09-13, this worker): `new X(a, b, …)` fills the class's
// root PROPERTY DECLARATIONS in SOURCE ORDER, one slot each — `on` handlers and
// methods take no slot, and `hlMembers` returns exactly that list in exactly that
// order, so the tree builder reads the signature straight off it. Three of those
// declarations are not properties of the COMPOSITION and are left out here:
//
// `View` and `Style` — what the component renders and paints WITH, not what it is
// constructed from. The language does give them a slot (a
// bare `new` binds them), but §12 says `Card { "text" }` with
// no declared property takes its text as FILL, and a
// component always declares a View: counting it would make
// the positional-literal fill unreachable in every component
// there is.
// `slot` / `$slot` — the late-bound child, not state (§12); and with the fill
// rendered where the child places it the two readings emit
// the same HTML anyway.
// every `static` — a static belongs to the CLASS (§12 build-time constants), so
// a reference cannot seed one for every other reference.
//
// A NAMED assignment does NOT free its slot — measured: `new Q('n1', beta = 'B', 'n2')`
// puts 'n2' in the SECOND declaration and 'B' in beta. It is applied AFTER the
// positional ones and wins, which is why the positional bindings are emitted first
// below. (COMPONENTS.md:711 reads "a property the reference also assigns by name is
// not in the signature"; the interpreter says otherwise and the parenthetical in the
// same line — "named is applied after positional; the name wins, as in `new`" — is
// what this follows.)
positionalSignature(key) {
let out = []
for (m of hlMembers(gen, key)) {
if (!m.isStatic && m.name != 'View' && m.name != 'Style' && m.name != 'slot' && m.name != '$slot') { out.push(m.name) }
}
return out
}
component(key, cls, childKey, v, at, path, inFor, rows) {
let bindings = []
let positional = []
let ons = []
let fill = []
let here = path.slice(0)
here.push(componentStep(cls, at))
let sig = positionalSignature(childKey)
let taken = 0
if (v != null) {
for (h of v.entries) {
let e = hlSyntax(gen, key, h)
if (e.tag == 'object_property') {
let val = hlSyntax(gen, key, e.value)
// A BINDING NAMES A DECLARED MEMBER OF THE CHILD (COMPONENTS §12): the value
// otherwise went into the construction and nowhere, with no word said
// (mission 322 row 12). An element entry is the fill, not a binding.
if (val.tag != 'object_expression' && !isMember(childKey, e.key)) {
hlError("hl:web: " + baseName(pathOf(key)) + ':' + e.line + ':' + e.col + " — " + cls + " has no member '" + e.key + "' to bind: " + baseName(pathOf(childKey)) + " declares " + positionalSignature(childKey).join(', '))
}
// A LITERAL ON A REFERENCE KEEPS ITS TYPE (§12 "typed, not stringified"):
// the binding carries the literal's KIND, and `view.refValue` turns the
// pair into the value the child's member is given. Written as text alone,
// `Level2 { n = 1 }` handed the child the String "1" and `n * 97` refused
// (measured 2026-09-14, demo-nested wall 3).
if (val.tag == 'literal') { bindings.push({ name = e.key; text = val.text; kind = val.kind; }) }
else if (val.tag == 'identifier') {
// a binding is a read at the reference site, so it is the same lookup
let r = nameRead(key, val.name, rows, val)
// …and a folded static crosses as its VALUE, for the same reason
if (r.k == 'text') { bindings.push({ name = e.key; text = r.text; kind = 'folded'; value = r.value; }) }
else { bindings.push({ name = e.key; member = val.name; }) }
}
else if (val.tag == 'member_expression') { bindings.push({ name = e.key; ref = ref(key, e.value, rows); }) }
else {
// `Card { span { … } }` — an element entry is not a binding, it is the FILL
let c = node(key, h, here, inFor, rows)
// …and an EXPRESSION is neither, so it is refused rather than dropped:
// the same rule an attribute follows (mission 312 wall 4).
if (c == null) {
hlError("hl:web: " + baseName(pathOf(key)) + ':' + val.line + ':' + val.col + " — '" + e.key + "' is bound to an expression on the reference " + cls + ", and a binding is a literal, a member or a field path: declare the expression at the root of " + baseName(pathOf(key)) + " (`" + e.key + "Value = …`) and write `" + e.key + " = " + e.key + "Value`")
}
fill.push(c)
}
} else if (e.tag == 'on_statement') {
// A HANDLER WRITTEN ON A REFERENCE IS THE HOST'S, bound on the child's ROOT
// element. The reference is a literal of THIS file's View, so its behaviour
// is minted from THIS file's site and its body reaches this file through the
// owner rule — the same path an element's own handler takes. The child's own
// handler on that element is not replaced: both are listeners on one element
// and both run, the child's first, because it was bound when the child's tree
// was claimed. (Until 2026-09-13 the event was collected here and dropped: a
// reference with `on submit` never bound, and a form submitted natively.)
// …AND ITS SITE, because the tables file this handler's write set
// under it: the browser repaints exactly what it wrote (mission 309).
ons.push({ event = e.event; site = baseName(pathOf(key)) + ':' + e.line + ':' + e.col; })
} else if (e.tag == 'member_expression' && !e.computed && styleRef(key, e)) {
// a `Style.rule` written on a reference: the reference renders no element
// of its own, so there is nothing for the class to land on (§12)
hlError("hl:web: " + baseName(pathOf(key)) + ':' + at.line + ':' + at.col + " — a Style rule cannot be written on the component reference '" + cls + "': a reference renders no element of its own. Write the rule on an element inside " + baseName(pathOf(childKey)) + ", or name a '#" + cls + "' local rule in this file")
} else {
// AN ORDERED ENTRY. A literal or a read is the next declared property's
// value while the signature has room — `Button { "SD" }` is `Button
// { label = "SD" }` — and everything else, plus everything that EXCEEDS
// the signature, is the FILL: a fragment of THIS file's View, with its
// reads, its handlers and its `for` rows (§12 "host content").
let c = node(key, h, here, inFor, rows)
if (c != null) {
if (taken < sig.length && (c.k == 'text' || c.k == 'member' || c.k == 'field')) {
// the same rule as the named form above: a literal keeps its kind and a
// folded static crosses as its value
if (c.k == 'text') { positional.push({ name = sig[taken]; text = c.text; kind = c.kind; value = c.value; }) }
else if (c.k == 'member') { positional.push({ name = sig[taken]; member = c.name; }) }
else { positional.push({ name = sig[taken]; ref = c; }) }
taken = taken + 1
} else { fill.push(c) }
}
}
}
}
// THE NAMED ASSIGNMENTS COME LAST, so the name wins over the positional entry that
// landed on the same property (measured: that is what `new` does)
let allBindings = []
for (b of positional) { allBindings.push(b) }
for (b of bindings) { allBindings.push(b) }
bindings = allBindings
// FILLING WHAT PLACES NO SLOT IS A LOCATED ERROR (§12): the child would drop the
// content silently, which is exactly the bug this rule was written for.
if (fill.length > 0 && !isMember(childKey, 'slot')) {
hlError("hl:web: " + baseName(pathOf(key)) + ':' + at.line + ':' + at.col + " — " + cls + " is filled here, but " + baseName(pathOf(childKey)) + " declares no 'slot' to fill: declare `slot = null` there and place `slot` in its View, or write the content outside the reference")
}
let classes = []
if (styleRules(key).includes('#' + cls) && !viewIds(key).includes(cls)) {
classes.push(view.localClass(key))
for (t of rootTags(childKey)) { noteRef(key, t, '#' + cls) }
}
// THE NODE NAMES ITS CHILD, it does not carry it. What the browser needs to build
// a child the server never mounted — the module url and the View tree — stands
// ONCE in the seed's blueprint table, keyed by this `key` (blueprintsIn below).
// The node used to carry that pair itself, and only when it stood inside a `for`:
// a child deeper in a minted child's own tree therefore had nothing to build from
// and was silently missing after a push (a comment card's like button and its
// edit history, creator's social app, 2026-09-13).
// THE REFERENCE'S OWN SITE: `file:line:col` of the reference literal, the id the
// JavaScript target mints ITS behaviour class under — what a handler written on
// the reference is built from, in the host's frame (client.hl bindRefOns)
let site = baseName(pathOf(key)) + ':' + at.line + ':' + at.col
return { k = 'component'; cls = cls; key = childKey; path = here; bindings = bindings; ons = ons; classes = classes; row = inFor; fill = fill; site = site; }
}
// ---- Style, the View side (§4, as the archive did it) --------------------------
// The tree builder writes the class on the element and REPORTS what it wrote
// (`styleRefs[key]` = [{ tag rule }]) and the element names it rendered
// (`styleTags[key]`); web/style.hl spells the selectors from those. Three ways
// a rule reaches an element: `Style.rule` written on it (class = the tag-prefix
// strip of the rule name), a `#rule` local of this file matching the element by
// NAME (class = this file's four-character class; `#Child` matches a composed
// child's root elements), and — decided in style.hl, no class — a rule named
// like an element of this file's own View.
styleRules(key) {
if (styleNames[key] != null) { return styleNames[key] }
let names = []
for (m of hlMembers(gen, key)) {
if (m.name == 'Style') {
let v = hlSyntax(gen, key, m.node)
for (h of v.entries) {
let e = hlSyntax(gen, key, h)
if (e.tag == 'object_property' && !names.includes(e.key)) { names.push(e.key) }
}
}
}
styleNames[key] = names
return names
}
noteRef(key, tag, rule) {
if (styleRefs[key] == null) { styleRefs[key] = [] }
for (r of styleRefs[key]) { if (r.tag == tag && r.rule == rule) { return null } }
styleRefs[key].push({ tag = tag; rule = rule; })
return null
}
noteTag(key, tag) {
if (styleTags[key] == null) { styleTags[key] = [] }
if (!styleTags[key].includes(tag)) { styleTags[key].push(tag) }
return null
}
// `#name` IS AN ID WHEN THE VIEW HAS ONE (creator's ruling, ticket #51 / R3): a
// `#name` rule targets the element with `id = 'name'` if this file's View writes
// that id, and is the file-local class of the elements named `name` otherwise. The
// ids are read off the View's SYNTAX before the tree is built, because an element
// named `name` may stand before the element that carries the id. Only a literal id
// counts — a member-bound one has no value until render. A component reference's
// own `id = …` is a binding for the child, not an element of this View; its fill is.
viewIds(key) {
if (styleIds[key] != null) { return styleIds[key] }
let out = []
let handle = viewHandle(key)
if (handle != 0) { idsIn(key, hlSyntax(gen, key, handle), false, &out) }
styleIds[key] = out
return out
}
idsIn(key, block, isRef, &out) {
if (block == null || block.entries == null) { return null }
for (h of block.entries) {
let n = hlSyntax(gen, key, h)
if (n != null && n.tag == 'object_property') {
let v = hlSyntax(gen, key, n.value)
if (v.tag == 'object_expression') { idsIn(key, v, componentKeyOf(key, n.key) != null, &out) }
else if (!isRef && n.key == 'id' && v.tag == 'literal' && !out.includes(v.text)) { out.push(v.text) }
} else if (n != null && n.tag == 'view_for') {
idsIn(key, hlSyntax(gen, key, n.body), false, &out)
} else if (n != null && n.tag == 'view_if') {
idsIn(key, hlSyntax(gen, key, n.consequent), false, &out)
let alt = hlSyntax(gen, key, n.alternate)
if (alt != null && alt.tag == 'view_if') { idsIn(key, { entries = [n.alternate] }, false, &out) }
else { idsIn(key, alt, false, &out) }
}
}
return null
}
// the root element tags of a component's tree (a composed child under `#Child`)
rootTags(key) {
let out = []
for (n of tree(key)) { if (n.k == 'el' && !out.includes(n.tag)) { out.push(n.tag) } }
return out
}
baseName(p) {
let i = p.lastIndexOf('/')
return i < 0 ? p : p.slice(i + 1)
}
element(key, tag, v, path, inFor, rows) {
let attrs = []
let children = []
let here = path.slice(0)
here.push(tag)
let domTag = view.isTag(tag) ? tag : view.kebab(tag)
// `body { }` IS THE PAGE'S BODY, and only as the View's root (COMPONENTS §6): below
// the root it rendered a second, nested <body> no browser keeps (mission 322 row 5)
if (domTag == 'body' && path.length > 0) {
hlError("hl:web: " + baseName(pathOf(key)) + ':' + v.line + ':' + v.col + " — a `body` element below the View's root: `body { … }` is the page's body and stands only as a View's root")
}
noteTag(key, tag)
let classes = []
for (h of v.entries) {
let e = hlSyntax(gen, key, h)
let styled = false
if (e.tag == 'member_expression' && !e.computed) {
let obj = hlSyntax(gen, key, e.object)
let prop = hlSyntax(gen, key, e.property)
if (obj.tag == 'identifier' && obj.name == 'Style') {
if (!styleRules(key).includes(prop.name)) { hlError("no Style rule named '" + prop.name + "' in " + key) }
if (prop.name.startsWith('#')) { hlError("'" + prop.name + "' in " + key + " is a LOCAL rule and applies by NAMING the element, not by being referenced — every '" + prop.name.slice(1) + "' this file's View renders already carries it; delete the reference") }
let cls = view.kebab(view.className(prop.name, tag)) // the class is kebab-case (creator, 2026-09-12)
if (!classes.includes(cls)) { classes.push(cls) }
noteRef(key, tag, prop.name)
styled = true
}
}
if (styled) {
// a Style reference is not a child
} else if (e.tag == 'object_property') {
let val = hlSyntax(gen, key, e.value)
if (val.tag == 'literal' && view.isBoolAttr(e.key) && val.kind == 'boolean') {
// A BOOLEAN ATTRIBUTE IS ITS PRESENCE (ticket #33): `disabled = true` is the
// attribute, `disabled = false` its absence — decided here, once, for every
// writer of the markup
if (val.text == 'true') { attrs.push({ name = e.key; text = ''; }) }
} else if (val.tag == 'literal') {
attrs.push({ name = e.key; text = val.text; })
} else if (val.tag == 'identifier') {
// THE SAME LOOKUP A TEXT CHILD USES: a folded static becomes the
// attribute's literal text, a member or a row stays a read
let r = nameRead(key, val.name, rows, val)
if (r.k == 'text' && view.isBoolAttr(e.key)) { if (view.boolOn(r.value)) { attrs.push({ name = e.key; text = ''; }) } }
else if (r.k == 'text') { attrs.push({ name = e.key; text = r.text; }) }
else { attrs.push({ name = e.key; member = val.name; }) }
} else if (val.tag == 'member_expression') {
attrs.push({ name = e.key; ref = ref(key, e.value, rows); })
} else {
let c = node(key, h, here, inFor, rows)
// AN EXPRESSION AS AN ATTRIBUTE VALUE IS REFUSED HERE, AND WAS DROPPED IN
// SILENCE (mission 312 wall 4). `span { id = 'L3t' + n }` rendered no `id`
// at all and said nothing — the element came back with empty attributes and
// the author had no line to look at. A View attribute takes a literal, a
// member or a field path; anything else is a member of this file, declared
// at its root. The nested-element form (`div { span { … } }`) is the entry
// whose value is a hybrid, and it is what `node` answers for above.
if (c == null) {
hlError("hl:web: " + baseName(pathOf(key)) + ':' + val.line + ':' + val.col + " — the attribute '" + e.key + "' is given an expression, and a View attribute is a literal, a member or a field path: declare the expression at the root of " + baseName(pathOf(key)) + " (`" + e.key + "Value = …`) and write `" + e.key + " = " + e.key + "Value`")
}
children.push(c)
}
} else {
let c = node(key, h, here, inFor, rows)
if (c != null) { children.push(c) }
}
}
// a `#tag` LOCAL rule of this file matches this element by name: the file's class
// — unless the View writes `id = 'tag'` somewhere, then the rule is that id's (R3)
if (styleRules(key).includes('#' + tag) && !viewIds(key).includes(tag)) {
let cls = view.localClass(key)
if (!classes.includes(cls)) { classes.push(cls) }
noteRef(key, domTag, '#' + tag)
}
if (classes.length > 0) {
let joined = ''
for (c of classes) { joined = joined == '' ? c : joined + ' ' + c }
let merged = false
for (a of attrs) {
if (a.name == 'class' && a.text != null) { a.text = a.text + ' ' + joined merged = true }
}
if (!merged) { attrs.push({ name = 'class'; text = joined; }) }
}
// (§6 sibling entries: inside the literal `tag` would name the entry just written,
// so the source key is taken before the literal is built)
let srcKey = tag
// THE SITE: `file:line:col` of the literal, the id the JavaScript target mints the
// literal's class under — the browser builds this element's literal from it
// (hlLiteralNew), so a row created after a list changed has a literal too
let site = baseName(pathOf(key)) + ':' + v.line + ':' + v.col
return { k = 'el'; tag = domTag; key = srcKey; path = here; attrs = attrs; children = view.implied(domTag, children, here, site); site = site; }
}
// ---- an instance and its state -------------------------------------------------
// THE ROUTE'S GROUPS ARE THE CONSTRUCTION'S NAMED ARGUMENTS (creator ruling
// 2026-09-12): `:id` is a parameter of the class like any other, set and pinned
// before its root runs, so `_post = db.fetch(id)` on line 1 sees it. Nothing is
// laid over an instance afterwards, and nothing is spelled with a sigil.
construct(key, params) {
return hlLoad(pathOf(key), params)
}
// THE VIEW IS COMPILER OUTPUT, NOT A VALUE — and so, for a render, is the Style.
// This half reads the View's SYNTAX (`tree()` below, through hlSyntax) and never its
// value; `state()` ships neither to the browser; the stylesheet is folded into class
// names at build, by a walk that constructs its OWN instance and reads `Style` there.
// Evaluating them for a render therefore built a behaviour literal per element per
// `for` row, per request, for nobody: half the construction time of a 2000-row
// component, measured 2026-09-14.
//
// The framework says so in the one way the language already offers: it PINS them.
// An explicitly passed construction value outranks every computed default (the
// creator's rule of 2026-07-26), and a pinned member does not compute its default at
// all. No language rule about a View was needed and none was added.
renderArgs(key, args) {
let out = args
if (declares(key, 'View')) { out.View = null }
if (declares(key, 'Style')) { out.Style = null }
return out
}
// does the file-class declare a member of this name?
declares(key, name) {
for (m of hlMembers(gen, key)) { if (m.name == name && !m.isStatic) { return true } }
return false
}
// THE FRAMEWORK'S OWN CONSTRUCTIONS — the sheet walk (a component is constructed to
// read its `Style`), an imported static's holder — happen outside any request, and a
// class's root runs at construction: `me = session.user` there would meet a null,
// which a real render never has (every request carries a session, minted if the
// browser brought none). So they are handed an ANONYMOUS session — nobody logged in,
// never saved — and the root takes its logged-out branch (the creator, 2026-09-13:
// /__hl/app.css was a 500 while the page it styles was 200).
anon = null
anonSession() {
if (anon == null) { anon = new Session(created = now(), seen = now()) }
return anon
}
// THE SESSION AT CONSTRUCTION. A component that declares a member `session` is
// constructed with the connection's session as that named argument — the same
// instance a server face gets as its trailing argument, and nothing ambient: a
// shell reads `me = session.user` at its root on the server, and a reload renders
// logged in (measured by the creator 2026-09-13: the shell rendered logged-out
// after a reload while the faces posted as alice). The browser gets only what a
// page may see of it (`state()` below), never the id the cookie carries.
constructionArgs(key, params, s, host) {
let wantsSession = declares(key, 'session')
let wantsHost = declares(key, 'host')
if (!wantsSession && !wantsHost) { return params }
let args = {}
for (k of params.keys()) { args[k] = params[k] }
if (wantsSession) { args.session = s }
if (wantsHost) { args.host = host }
return args
}
// THE HOST AT CONSTRUCTION (ticket #74), by the same rule: a component that declares
// a member `host` is constructed with the host the request named — the `Host`
// header without its port — so an app answering one address per subdomain renders
// the right page on the server. A navigation takes it from ITS carrier: the socket's
// upgrade request, or the POST's own. Null where the request named none, and for the
// framework's own constructions above, which answer no request.
hostOf(header) {
if (header == null || header == '') { return null }
let h = header.trim()
// an IPv6 literal keeps its brackets: `[::1]:8080` is `[::1]`
if (h.startsWith('[')) {
let close = h.indexOf(']')
return close < 0 ? h : h.slice(0, close + 1)
}
let colon = h.indexOf(':')
return colon < 0 ? h : h.slice(0, colon)
}
state(key, page) {
let out = {}
for (m of hlMembers(gen, key)) {
if (m.name != 'View' && m.name != 'Style' && !m.isStatic) {
// A FUNCTION MEMBER IS NOT STATE. JSON has no form for it, and shipping
// it as null would PIN null over the browser's own declaration (a
// construction argument outranks the default) — so it is left out, and
// the browser's instance evaluates `hideBadge = () => { … }` itself.
if (m.name == 'session') {
// the session's PUBLIC part: who is logged in — the id stays on the server
out.session = page.session != null ? { user = page.session.user } : null
} else if (hlTypeName(page[m.name]) != 'Function') { out[m.name] = page[m.name] }
}
}
return out
}
// everything the browser needs about one mounted component — and its children:
// every component node of its tree is a mount of its own, constructed with the
// bindings evaluated against THIS instance, keyed by the node's path
mount(key, params, s, host) {
let page = construct(key, renderArgs(key, constructionArgs(key, params, s, host)))
let m = { key = key; params = params; view = tree(key); state = state(key, page); page = page; kids = {}; session = s; host = host; }
mountKids(&m, m.view, {}, '')
return m
}
// `rowKey` is what tells one row's child from the next one's: the index of every
// enclosing `for` iteration, appended to the component node's path. A component
// outside every `for` has the empty rowKey and keeps the key it always had.
mountKids(&m, nodes, rows, rowKey) {
for (n of nodes) {
if (n.k == 'component') {
let args = {}
for (b of n.bindings) {
if (b.text != null) { args[b.name] = view.refValue(b) }
else if (b.member != null) { args[b.name] = view.value({ k = 'member'; name = b.member; }, m.page, rows) }
else if (b.ref != null) { args[b.name] = view.value(b.ref, m.page, rows) }
}
m.kids[view.kidKey(n.path) + rowKey] = mount(n.key, args, m.session, m.host)
// THE FILL IS THIS FILE'S FRAGMENT, not the child's: a component standing
// inside it is a child of THIS mount, evaluated in THIS scope
if (n.fill != null) { mountKids(&m, n.fill, rows, rowKey) }
} else if (n.k == 'el') {
mountKids(&m, n.children, rows, rowKey)
} else if (n.k == 'if') {
mountKids(&m, n.then, rows, rowKey)
mountKids(&m, n.other, rows, rowKey)
} else if (n.k == 'for') {
// ONE MOUNT PER ROW: the row is the scope the bindings are evaluated in,
// so the child is constructed once per entry, with that entry's values
let entries = view.value(n.list, m.page, rows)
if (entries != null) {
let ri = 0
for (entry of entries) {
let inner = rows + {}
inner[n.row] = entry
// THE ROW'S KEY, not its index: a child of a row travels with the
// record it was mounted for (view.rowKey, the one rule the server's
// HTML walk and the browser's region read too)
mountKids(&m, n.body, inner, rowKey + '#' + view.rowKey(entry, ri))
ri = ri + 1
}
}
}
}
return null
}
// the route component and, if it declares one, its wrapping shell
mounts(m, s, host) {
let key = keyOf(m.route.component)
let out = { page = mount(key, m.params, s, host); shell = null; }
let w = hlFile(gen, key).wrapper
if (w != null) { out.shell = mount(w, m.params, s, host) }
return out
}
// A MOUNT IS NOT ITS TREE. What the browser needs per mount is what makes THIS one
// this one — its key, the route's params, the state the server evaluated, its
// children — while the View tree belongs to the COMPONENT and stands once in the
// seed's blueprint table under the same key. Shipping it per mount put the same tree
// in the payload as many times as the page mounted that component.
ship(mount) {
let kids = {}
for (k of mount.kids.keys()) { kids[k] = ship(mount.kids[k]) }
return { key = mount.key; params = shipParams(mount.params); state = mount.state; module = moduleUrl(mount.key); kids = kids; }
}
\* A FUNCTION-VALUED BINDING IS NOT SHIPPED — the same rule `state` keeps for a
function MEMBER, for the same reason. A routine a host hands a child
(`PostForm { onPosted = ... }`) has no JSON form, and shipping it as null
would PIN null over the browser's own binding: a construction argument
outranks what the client evaluates. It is left out, and the browser binds it
from the host instance when it builds the mirror, exactly as it does for a
member. Until mission 320 it rode the wire as null because `JSON.stringify`
invented that null; the language refuses to now, which is what made the lie
visible. *\
shipParams(params) {
let out = {}
for (k of params.keys()) {
if (hlTypeName(params[k]) != 'Function') { out[k] = params[k] }
}
return out
}
// A COMPONENT IS SERVED AT ITS OWN `.hl` URL. A browser executes a module by
// its MIME type, never by its extension, so `text/javascript` on
// `/components/home.hl` is a module — and the url the page loads is then the
// path the author wrote in the route table, with nothing renamed in between.
// The route that answers it is the APP's (a `function` route in the manifest),
// because where an app serves its modules from is the app's to say.
moduleUrl(key) {
return '/' + key
}
// A PACKAGE'S BROWSER HALF IS SERVED BESIDE THE RUNTIME. Not a convention this
// file invents: the compiler derives the specifier it writes into every importing
// module from the runtime url it is handed, and for the same reason that url is
// one member here — one url means ONE ES-module instance, and two would be two
// copies of the package's browser state. This is that derivation, on this side.
halfUrl(pkg) {
return halfDir + '/' + pkg + '/client.js'
}
// The module of the `.hl` url a request names — the on-demand half of the
// transpile. The app's function route hands the path here.
serveHl(urlPath) {
let js = module(urlPath.slice(1))
if (js == null) { return notFound(urlPath) }
return new Response(js, { headers = { 'Content-Type' = 'text/javascript; charset=utf-8' } })
}
// ---- the stylesheet -------------------------------------------------------------
// A `Style { }` member is an ORDINARY member of the file's class, so its value
// is what a construction produces — the statics it reads already folded, the
// `+` rule merge already the language's. That is the whole input; style.hl does
// the walk. The project's styles file comes first so its global rules stand
// under every component's, then every component this server can mount, in the
// order `served` holds them (the pages and the wrapper chain above them — the
// same set that has a browser module).
stylesheet() {
if (sheetText == null) {
css.gen = gen
css.view = view
let files = []
if (styles != null) {
// THE STYLES FILE: root members, its inherits first. It has to be in the
// graph (the app imports it) — its rules are read in authored order off
// the syntax and their values off the constructed instance.
let tokenKeys = [] // the token files already walked
for (sk of inheritChain(keyOf(styles))) {
if (graph.files[sk] == null) { hlError("the styles file " + sk + " is not in the project graph — import it from the app's entry so its rules can be read in authored order") }
// A TOKEN FILE the styles file member-imports (`import { dark } from './tokens.hl'`,
// there `static dark = var('#123')`) is walked BEFORE it, so its var() tokens are
// named and written into :root first. Before ticket #39 part 2 only the chain's own
// non-static members were named, and every imported token was an unknown id: a 500
// "a css variable is used before any styles file declared it". (The architect's
// patch from mission 021 of the tickets app, taken upstream.)
for (tk of tokenFilesOf(sk)) {
if (!tokenKeys.includes(tk)) {
tokenKeys.push(tk)
files.push({ key = tk; cls = graph.files[tk].class; rules = tokenRules(tk); aliases = []; refs = []; tags = []; hasView = false; isStyles = true; })
}
}
let inst = hlLoad(pathOf(sk), {})
let rules = []
let own = {}
for (m of hlMembers(gen, sk)) {
if (!m.isStatic && m.node != 0) {
let v = hlSyntax(gen, sk, m.node)
// a merged rule (`a = b + { … }`) is a block too (css.entriesOf)
rules.push({ key = m.name; node = m.node; value = inst[m.name]; isBlock = v != null && (v.tag == 'object_expression' || (v.tag == 'binary_expression' && css.isHybridValue(inst[m.name]))); })
own[m.name] = true
}
}
// EACH FILE OF THE CHAIN IS ITS OWN INSTANCE, so a token it INHERITS is a second
// CssVar with its own id: `body { color = dark }` in the child held an id the
// walker never named (ticket #39 part 1). The inherited tokens are registered
// under their names as ALIASES — named, never written into :root a second time.
let aliases = []
for (pk of inheritChain(sk)) {
if (pk != sk) {
for (m of hlMembers(gen, pk)) {
if (!m.isStatic && own[m.name] == null && css.isVar(inst[m.name])) { aliases.push({ key = m.name; value = inst[m.name]; }) }
}
}
}
// the styles file's ROOT is collected here and not by css.entriesOf, so the
// same refusal has to be raised here: two `@media` root members are one
// name with one value and would emit the first block empty
css.guardMedia(sk, rules)
files.push({ key = sk; cls = graph.files[sk].class; rules = rules; aliases = aliases; refs = []; tags = []; hasView = false; isStyles = true; })
}
}
for (k of served.keys()) {
if (hasStyle(k)) {
tree(k) // the refs and tags are collected while the tree is built
let inst = construct(k, constructionArgs(k, {}, anonSession(), null))
files.push({ key = k; cls = graph.files[k].class; rules = css.entriesOf(k, styleNode(k), inst.Style); refs = styleRefs[k] != null ? styleRefs[k] : []; tags = styleTags[k] != null ? styleTags[k] : []; ids = viewIds(k); hasView = viewHandle(k) != 0; isStyles = false; })
}
}
sheetText = css.sheet(files)
}
return sheetText
}
// the .hl files a styles file member-imports that hold var() tokens (a package like
// hl:web/css is skipped), in import order
tokenFilesOf(key) {
let out = []
for (imp of graph.files[key].imports) {
if (imp.key != null && !imp.key.startsWith('hl:') && imp.names != null && imp.names.length > 0 && graph.files[imp.key] != null) {
if (!out.includes(imp.key) && tokenRules(imp.key).length > 0) { out.push(imp.key) }
}
}
return out
}
// a token file's var() tokens as styles-file root rules, in authored order — EVERY static
// token of the file, not only the imported names (a token may name another). The values
// are the file's statics, evaluated once per process: the same CssVar instances, with the
// same ids, the importer holds.
tokenRules(key) {
let rules = []
let inst = null
for (m of hlMembers(gen, key)) {
if (m.isStatic && m.node != 0) {
if (inst == null) { inst = hlLoad(pathOf(key), {}) }
let v = inst[m.name]
if (css.isVar(v)) { rules.push({ key = m.name; node = m.node; value = v; isBlock = false; }) }
}
}
return rules
}
// a file and the files it inherits, parents first (the cascade order of a styles chain)
inheritChain(key) {
let out = []
let f = graph.files[key]
if (f != null && f.inherits != null) {
for (p of f.inherits) { for (k of inheritChain(p)) { if (!out.includes(k)) { out.push(k) } } }
}
out.push(key)
return out
}
styleNode(key) {
for (m of hlMembers(gen, key)) { if (m.name == 'Style') { return m.node } }
return 0
}
hasStyle(key) {
for (m of hlMembers(gen, key)) {
if (m.name == 'Style') { return true }
}
return false
}
// ---- rendering ------------------------------------------------------------------
// ONE MOUNT'S HTML, FROM ITS COMPILED RENDER. The old hl:web walked the View tree per request —
// a branch per node, an attribute string built again, the indentation of every line
// decided again. Every one of those is a fact about the View, so this framework
// compiles the component once into a list of steps (constant text, and a read with its
// own closure) and a request concatenates them (compile.hl `serverSteps`). The bytes
// are the same bytes: the structure the walk would have produced is the structure the
// steps carry.
renderOf(mount, nodes, indent, slot) {
let inst = mount.page
let rows = {}
let ctx = { slot = slot; kids = mount.kids; }
return compiler.runSteps(compiler.serverSteps(mount.key, nodes, indent, null, slot != null), &inst, &rows, &ctx)
}
document(ms, s) {
// the page inside the shell: readable by default (elements one per line, the
// child page at the slot's own depth), one line when `minify` is set
let nl = minify ? '' : newline
let indent = minify ? null : tab
let inner = null
let body = null
if (ms.shell != null) {
// `body { … }` as the shell's View root IS the page body (COMPONENTS §6):
// render its children into the document's body instead of nesting one
let root = ms.shell.view
if (root.length == 1 && root[0].k == 'el' && root[0].tag == 'body') { root = root[0].children }
// the child page is rendered at the depth the slot stands: the shell is
// rendered first with a marker, then the marker's own indentation is read
let marker = ''
let shellHtml = renderOf(ms.shell, root, indent, marker)
let slotIndent = null
if (!minify) {
let at = shellHtml.indexOf(marker)
let lineStart = shellHtml.lastIndexOf(newline, at) + 1
slotIndent = shellHtml.slice(lineStart, at)
inner = renderOf(ms.page, ms.page.view, slotIndent, null)
// block() begins each element with a newline at its indent; the marker
// already sits on such a line, so the first newline and indent are dropped
body = shellHtml.replace(newline + slotIndent + marker, inner)
} else {
inner = renderOf(ms.page, ms.page.view, null, null)
body = shellHtml.replace(marker, inner)
}
} else {
body = renderOf(ms.page, ms.page.view, indent, null)
}
let seed = seedFor(ms)
// THE PAGE'S MODULE SCRIPT: two imports and one construction. No component
// is imported here — the seed carries each mount's module url and the Client
// loads it (hlLoad → dynamic import) when it mounts it, so a page ships the
// code for the route it IS and not for every route the app has.
//
// AND IT SAYS WHICH REALM THIS IS. A compiled module never sets its own
// realm (the language has no manifest inside a module compile), and the
// runtime's default is the neutral 'server' — under which a browser's
// `emit server x()` would dispatch LOCALLY instead of crossing and an
// `on client y()` would be skipped. The name is not invented here: it is the
// realm the manifest declares web/client.hl as the entrypoint OF.
let t = minify ? '' : tab
let head = nl + t + '<meta charset="utf-8">'
head = head + nl + t + '<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">'
// THE HEAD METADATA (creator, 2026-09-13). One rule for all of it: the PAGE's
// member wins, the APP's manifest setting is the default, and nothing is
// invented — a value is written out as the app wrote it, escaped.
// `__title` / `appTitle` → <title> and og:title
// `__description` / `appDescription` → meta description and og:description
// `__image` / `appImage` → og:image (the url AS GIVEN — a relative
// one stays relative; the host is not guessed)
// `__favicon` / `appFavicon` → <link rel="icon" href="…">
// `__meta` / `meta` → a list of hybrids, one <meta> each with
// exactly the attributes named:
// `{ name = 'robots' content = 'noindex' }`,
// `{ property = 'og:type' content = 'article' }`.
// The app's list first, the page's appended after;
// the attributes of one entry stand in the
// hybrid's key order.
// ALL FIVE ARE PAGE MEMBERS, so they are also SITES of the page mount in the
// browser (client.hl): a handler's write, an inbound push or a navigation
// repaints the head element the same way a member repaints an element. What
// this writes is the first answer; the browser keeps it in step from there.
let h = headOf(ms)
if (h.title != null) {
head = head + nl + t + '<title>' + view.escape(h.title) + '</title>'
head = head + nl + t + '<meta property="og:title" content="' + view.escape(h.title) + '">'
}
if (h.description != null) {
head = head + nl + t + '<meta name="description" content="' + view.escape(h.description) + '">'
head = head + nl + t + '<meta property="og:description" content="' + view.escape(h.description) + '">'
}
if (h.image != null) { head = head + nl + t + '<meta property="og:image" content="' + view.escape(h.image) + '">' }
if (h.favicon != null) { head = head + nl + t + '<link rel="icon" href="' + view.escape(h.favicon) + '">' }
for (m of h.meta) {
let attrs = ''
for (k of m.keys()) { attrs = attrs + ' ' + k + '="' + view.escape(m[k]) + '"' }
head = head + nl + t + '<meta' + attrs + '>'
}
// THE PAGE'S OWN META TAGS ARE MARKED. They are the page mount's state in the
// browser (client.hl paints `__meta` as a group), so the client has to be able
// to replace exactly these and leave the app's manifest tags above them alone.
for (m of h.pageMeta) {
let attrs = ''
for (k of m.keys()) { attrs = attrs + ' ' + k + '="' + view.escape(m[k]) + '"' }
head = head + nl + t + '<meta' + attrs + ' data-hl-page-meta>'
}
head = head + nl + t + '<link rel="stylesheet" href="' + styleUrl + '">'
head = head + nl + t + '<script type="module">'
head = head + 'import { hlNew, hlSetRealm } from "' + runtimeUrl + '";'
head = head + 'import { Client } from "' + clientUrl + '";'
head = head + 'hlSetRealm(' + scriptLiteral(clientRealm()) + ');'
head = head + 'window.__hl = await hlNew(Client, [' + scriptLiteral(JSON.stringify(seed)) + ']);'
head = head + '</script>' + nl
return '<!doctype html>' + nl + '<html>' + nl + '<head>' + head + '</head>' + nl + '<body>' + body + nl + '</body>' + nl + '</html>' + nl
}
// A VALUE WRITTEN INTO THE INLINE <script> (ticket #34). The seed carries the app's
// members, user text among them, and JSON.stringify leaves `<` alone: a text holding
// `</script>` ended the script early and the rest of it was parsed as HTML (stored XSS
// in every app). `\u003c` is the same character to the JavaScript string literal and
// nothing to the HTML parser; U+2028/2029 are escaped the same way for older engines.
// A `<` is never part of a JSON escape, so the replacement cannot split one.
scriptLiteral(v) {
let text = JSON.stringify(v).replaceAll('<', '\u003c')
text = text.replaceAll(JSON.parse('"\u2028"'), '\u2028')
return text.replaceAll(JSON.parse('"\u2029"'), '\u2029')
}
// ---- THE BOUNDARY ---------------------------------------------------------------
// The frames are the LANGUAGE's (SPEC "The boundary wire protocol"), not this
// framework's: every edge module of every realm speaks exactly these, and what
// differs per edge is only the carrier. This one carries two.
//
// peer → realm { t:"emit", i, event, payload } { t:"ping" }
// realm → peer { t:"ack", i, ok, value } { t:"emit", event, payload } { t:"pong" }
//
// A crossing emit does NOT come in through here on its way out: the language
// announces it on the realm broadcast bus and the tap below turns it into the
// outward frame. That is what makes this file an edge module rather than a
// place the language knows about.
// A SAVE. Re-analyse; if the graph reads the same (a store write, an asset, a
// comment) nothing happens; otherwise the graph, the trees, the modules and the
// sheet are dropped and every open tab is told to reload — the page it fetches is
// rendered from the new analysis.
on hlFileChanged(ev) {
if (!watchMode) { return null }
// only a source file: a store write, an asset or an editor's temp file is not a
// change to the program (the graph's file listing cannot tell a View's text
// changed, so the event's name decides, not a comparison of analyses)
if (!ev.name.endsWith('.hl')) { return null }
// one save arrives as a burst of events (measured: three to four); one re-analysis
// and one reload per burst
if (now() - lastChange < 500) { return null }
lastChange = now()
let fresh = hlProject()
graph = fresh
gen = graph.analysisGen
trees = {}
slotAt = {}
modules = {}
sheetText = null
styleNames = {}
styleRefs = {}
styleTags = {}
styleIds = {}
console.log('framework: ' + ev.name + ' changed — re-analysed (generation ' + gen + '), tabs reloading')
for (k of peers.keys()) {
let c = peers[k]
if (c != null) { c.send(JSON.stringify({ t = 'build' })) }
}
return null
}
on http.connect(client) {
peers['c' + client.id] = client
// THE SESSION IS NAMED AT THE HANDSHAKE (the archive's design, hybrilior's
// before it): the upgrade is an HTTP request and carries the cookie, the
// connection carries it here, and page script never sees the id. An id nobody
// knows, or none, is an anonymous connection.
peerSession['c' + client.id] = sessions.resolve(client.cookie)
// and the host it was dialled at, which a navigation over it renders for (ticket #74)
peerHost['c' + client.id] = hostOf(client.host)
}
on http.close(client) {
peers['c' + client.id] = null
peerSession['c' + client.id] = null
peerHost['c' + client.id] = null
peerMounts['c' + client.id] = null
}
on http.message(client, text) {
let frame = JSON.parse(text)
if (frame.t == 'ping') { client.send(JSON.stringify({ t = 'pong' })) return null }
if (frame.t == 'emit') { client.send(inbound(client, frame)) return null }
// `sub` / `unsub` are the subscription set, and subscriptions belong to the
// next framework (SPEC says the peer owns the set and resends it on every
// open). Acked so a peer that sends one is not left waiting.
if (frame.t == 'sub' || frame.t == 'unsub') { client.send(JSON.stringify({ t = 'ack'; i = frame.i; ok = true; })) return null }
// `hello`: what the tab has mounted; `mounts`: the same after a navigation.
// That is what fan-out reads beside the session the handshake named.
if (frame.t == 'hello' || frame.t == 'mounts') {
peerMounts['c' + client.id] = frame.mounts
client.send(JSON.stringify({ t = 'ack'; i = frame.i; ok = true; }))
return null
}
console.warn('framework: unknown frame kind', frame.t)
return null
}
// ONE INBOUND EMIT, dispatched and acked. `ok` is the whole truth for a durable
// queue — an entry leaves it on the ack, never on a value — so a face that
// raised nothing acks true with no `value` key, byte-identical to the ack a
// statement-form emit always got.
inbound(client, frame) {
let faces = facesOf(frame.event)
let ack = { t = 'ack'; i = frame.i; ok = true; }
if (faces.length == 0) {
// The far realm cannot see what this one declares, so this is the ONLY
// place the absence is visible. A value-form emit with no answerer is
// the located error SPEC describes, and it is located HERE, at the
// handler that does not exist.
ack.ok = false
ack.error = "no class in the '" + serverRealm() + "' realm declares a handler for '" + frame.event + "' — a value-form emit needs an ANSWERER, and this event has none"
return JSON.stringify(ack)
}
// A PEER NEVER FILLS THE SESSION (ticket #16, SPEC "A face's `session` is the
// server's"). A face whose last parameter is `session` gets the connection's session
// in that slot; the peer's arguments fill the slots before it. A frame with more
// arguments than those slots would have put the peer's own object where the session
// goes, one extra argument and the face trusted it, so it is refused, located at
// the face, before anything runs.
for (key of faces) {
let h = faceOf(key, frame.event)
if (takesSession(h) && frame.payload.length > h.params.length - 1) {
ack.ok = false
ack.error = "hl:web: " + key + ':' + h.line + ':' + h.col + " — '" + frame.event + "' takes " + (h.params.length - 1) + " argument(s) and the session, and this emit sent " + frame.payload.length + ": the `session` parameter is filled by the server, never by the peer"
postSession = null
postHost = null
return JSON.stringify(ack)
}
}
// THE EMITTING CONNECTION is what an outward emit raised inside a face
// reaches (SPEC: scoped to the emitting connection, sent BEFORE the ack).
sending = client
posting = client == null
postEmits = []
let value = null
// THE SESSION IS A FACE'S TRAILING ARGUMENT: `on server create(text, session)`.
// A face on a blank instance has its arguments and its imports; the session is
// handed to it like the rest, never read from an ambient name. Where it comes
// from is the carrier's: the handshake's session over the socket, the cookie's
// of the request over the POST (the route above put it in `postSession`).
let s = client != null ? peerSession['c' + client.id] : postSession
faceHost = client != null ? peerHost['c' + client.id] : postHost
if (s != null) { sessions.touch(s) }
// `&args`: a call argument is a copy, an INSTANCE inside it included (measured
// 2026-09-12: a session handed through a plain argument was a copy, and the
// face's login wrote the copy); the reference form hands the list itself.
// ONE LIST PER FACE: the session lands in each face's own `session` slot, the
// arguments the peer left out read null (a face without one: appended, as ever).
for (key of faces) {
let h = faceOf(key, frame.event)
let args = frame.payload.slice(0)
if (takesSession(h)) {
while (args.length < h.params.length - 1) { args.push(null) }
}
args.push(s)
let answer = dispatch(key, frame.event, &args)
if (value == null) { value = answer }
}
sessions.save(s) // whatever a face wrote on it is on disk now
sessions.maybeSweep(liveSessionIds())
sending = null
if (value != null) { ack.value = value }
// the frames this face raised for a caller that has no connection (above)
if (posting && postEmits.length > 0) { ack.emits = postEmits }
posting = false
postEmits = []
postSession = null
postHost = null
faceHost = null
return JSON.stringify(ack)
}
// THE SERVER FACES of an event: every file the graph holds that declares
// `on <server realm> <event>()` unscoped. The graph is the only thing that
// knows — a framework never scans a directory and never reads a file to find
// out what it declares.
facesOf(event) {
let out = []
for (key of graph.files.keys()) {
for (h of graph.files[key].handlers) {
if (h.event == event && h.realm == serverRealm() && h.scope == null) {
if (!out.includes(key)) { out.push(key) }
}
}
}
return out
}
// the server face of `event` in this file, as the analysis reads it (`params` is on
// this entry; the graph's handler rows do not carry it)
faceOf(key, event) {
for (h of hlEvents(gen, key).handles) {
if (h.event == event && h.realm == serverRealm() && h.scope == null) { return h }
}
return null
}
// does this face take the session? Its LAST parameter is named `session`.
takesSession(h) {
return h != null && h.params != null && h.params.length > 0 && h.params[h.params.length - 1] == 'session'
}
// ONE FACE. A face is a FUNCTION over its arguments, its imports, its statics
// and the session — so the target is the CLASS and the language dispatches on a
// blank instance of it: no construction, no member initializer, nothing of the
// file evaluated. This framework's OWN faces are the exception, and not an
// exception to that rule: `web/server.hl` is not a component, it is the running
// edge module, and its face reads the routes and the graph it was constructed

Only the first lines are shown.

Branches

mainmain branch

Latest commits

4a2d7125initial commitmre2026-09-25 19:10