tickets

169.8 KB

1. // The framework's server half — the SERVER REALM's entrypoint, and the EDGE
2. // MODULE for the carriers the manifest declares.
3. // Its jobs: answer a URL with the HTML of a constructed component (SSR), ship
4. // the browser the client, the View tree and the state to continue from, carry
5. // the boundary in both directions (a websocket on the same port, a POST for a
6. // peer that has none), and run the server faces an inbound emit names.
7. import { NativeWebSocketServer, Response, randomToken } from 'hl:http1'
8. import HlwView from './view.hl'
9. import HlwRouter from './router.hl'
10. import HlwSessions from './sessions.hl'
11. import HlwSession from './session.hl'
12. // the Style walk — named Css here because `Style` is a well-known MEMBER name
13. import HlwCss from './css.hl'
14. import HlwCompile from './compile.hl'
15. import { readFile, exists, watch } from 'hl:fs'
16. import { file, env, args } from 'hl:proc'
17. import { now } from 'hl:time'
18. import { sha256 } from 'hl:crypto'
19. import { newline, tab } from './view.hl'
21. Hybrid routes = [] // bound by `new WebFrameworkServer(routes = …)`
22. // THE PROJECT'S STYLES FILE, declared by the app as a property of the framework:
23. // `new WebFrameworkServer(…, styles = './styles.hl')`. A file of statics and one
24. // `Style { }` root member (COMPONENTS §4) — the design tokens and the global
25. // rules, under every component's own Style in the one stylesheet. null: none.
26. styles = null // the app's styles file: the class it imported, or a path
27. // WHO AN OUTWARD EVENT IS FOR (creator, 2026-09-12): per event, a function the app
28. // declares — `audience = { postCreated = (p, session) => … }` — called for every
29. // connection that has a listener for the event mounted, with the event's
30. // arguments and that connection's session; a true answer sends the frame. An
31. // event with no entry reaches the emitting connection only. Only the app knows
32. // who is entitled; the face stays pure; the framework applies the answer.
33. Hybrid audience = {}
34. // THE SESSION STORE (the archive's manifest members, mission 252/255): nothing said →
35. // `<project>/.sessions`; a path → that path; `false` → memory only. The three clocks
36. // are seconds; null takes the layer's defaults (14 days valid, 15 min resident, sweep
37. // every 5 min).
38. // THE DEV WATCHER (the archive's `watch`): every save under the project arrives as an
39. // event; a save that changes the analysis re-reads the graph, drops every cache and tells
40. // every open tab to reload. Off by default — a deploy never re-analyses itself.
41. Boolean minify = false // production: one-line HTML, compact JavaScript modules
42. Boolean watchMode = true
43. lastChange = 0 // epoch ms of the last save acted on (the debounce)
44. String | Boolean sessionDir = null
45. Number sessionMaxAge = null
46. Number sessionIdle = null
47. Number sweepInterval = null
48. // THE SESSION COOKIE'S NAME (ticket #10). Cookies ignore the port, so two apps on one
49. // host that both answered `hlsid` overwrote each other's sessions; an app names its own.
50. // null: `hlsid`.
51. String sessionCookie = null
52. // THE COOKIE'S `Secure` FLAG (ticket #27): true when the app is reached over https —
53. // behind a TLS proxy the server itself speaks plain http and cannot tell, so the app
54. // says so. The browser then never sends the session over plain http. false: not set.
55. Boolean sessionSecure = false
56. // THE COOKIE'S `Domain` (ticket #44): 'example.org' shares one session with every
57. // <sub>.example.org, which a host-only cookie cannot. null: host-only, no attribute.
58. String sessionDomain = null
59. \* THE PORT: the app's own `--port=N` argument (hybriel hands every argument
60. after the entry to the program, creator ruling 2026-09-27), else the
61. constructor's, else HL_PORT (hybriel resolves PORT and `.env` into it),
62. else 8080. *\
63. Number port = null
64. // THE OFFLINE ALLOW-LIST (COMPONENTS §10, D38): the pages this app promises with the
65. // network down, named as the route table names them — the imported class or a path
66. // string. null: no service worker, no cache, no IndexedDB, nothing on the device.
67. offline = null
68. // THE OFFLINE FALLBACK PAGE (ticket #120): a data-free page — a route component with no
69. // parameters, the class or its path string — the service worker keeps once, fetched with
70. // NO credentials, and shows for any page it has nothing for while the network is down.
71. // null: the "Unavailable offline" page, as before. Needs `offline`.
72. offlineFallback = null
73. // THE DEAD-SOCKET CLOCK (COMPONENTS §10), in seconds. The browser pings every `pingEvery`,
74. // and a socket whose pong has not come back within `pongWithin` is taken for dead: it is
75. // closed, and the reconnect and the queue's replay start. A network that drops without a
76. // close frame is noticed within pingEvery + pongWithin (35 s by default). null: 25 and 10.
77. Number pingEvery = null
78. Number pongWithin = null
79. // AN UPLOAD THAT GOES SILENT — no progress, no answer — is read as dropped after this
80. // many seconds (COMPONENTS §10, an emit's file). null: 15.
81. Number uploadStall = null
82. // THE LARGEST FILE AN EMIT MAY CARRY (ticket #94), in bytes: a bigger one is refused
83. // at its first request, and the emit ends with that error. 1 GiB.
84. Number uploadMax = 1073741824
85. String host = null // the interface to bind; null → HL_HOST/HOST, the manifest's `host`, 0.0.0.0
87. // THE ONE RUNTIME URL, and the reason it is a member and not a literal in two
88. // places: a module's `import … from "./hl-runtime.js"` resolves against the
89. // MODULE's own url, so a server answering modules at two directory depths hands
90. // the browser two runtime urls — two ES-module instances, two `globalEvents`
91. // buses, two `__hlRealm` variables, and a crossing emit announced on a bus the
92. // edge module never taps. Every module this server compiles is handed this one
93. // specifier (hlJs's third argument).
94. // THE DIRECTORY THE FRAMEWORK ANSWERS FROM, and the reason it is its own member:
95. // a package's browser half is served BESIDE THE RUNTIME, and the compiler derives
96. // that url from the runtime's own (`js_module.zig browserHalfUrl`:
97. // `<dirname(runtime)>/<pkg>/client.js`). Two sides deriving one url from one
98. // directory is what keeps the module's `import` and this server's route table
99. // from drifting apart.
100. static halfDir = '/__hl'
101. static runtimeUrl = halfDir + '/hl-runtime.js'
102. clientUrl = halfUrl('web')
103. styleUrl = halfDir + '/app.css'
104. // THE BUILD'S VERSION IS IN EVERY URL THE BROWSER CACHES (after ticket #82): the
105. // runtime, the package halves, the component modules and the stylesheet were served
106. // at fixed urls, and a browser or Cloudflare kept the old client against a new
107. // deploy's pages. Each is now asked for as `<url>?v=<hash>`, the hash of everything
108. // this build serves, and answered with a year's `immutable` caching — a new build is
109. // a new url. The modules are COMPILED against this mark and it is replaced with the
110. // hash when they are served: the hash is of the compiled texts, so it cannot be in
111. // them while they are compiled, and a binary's baked modules carry the mark too (the
112. // one form both paths share). The route patterns stay the bare paths.
113. static buildMark = '?v=__hlbuild__'
114. static runtimeSpec = runtimeUrl + buildMark
115. // the web app manifest and the service worker's entry script (COMPONENTS §10)
116. static manifestUrl = halfDir + '/manifest.webmanifest'
117. static workerUrl = halfDir + '/sw.js'
119. // THE FRAMEWORK'S OWN URLS ARE ROUTES (creator: "just use routes"), appended to
120. // the app's table with `routes[] = …` — the append that takes on a caller's
121. // pinned argument during construction, where `routes = routes + […]` is dropped.
122. // Three of them here — the runtime, the REST carrier and the app's one
123. // stylesheet — and then one per PACKAGE BROWSER HALF the app's graph holds,
124. // appended below where the graph is known. There is no catch-all that compiles
125. // any graph file a url names.
126. routes[] = { pattern = runtimeUrl framework = true function = (route, req) => {
127. return new Response(runtime, { headers = cached(req, 'text/javascript; charset=utf-8') })
128. } }
129. // THE REST CARRIER, the same emit/ack pair for a peer that cannot hold a socket
130. // (SPEC: `POST /__hl/emit`).
131. // ITS SESSION IS THE COOKIE'S (creator, 2026-09-14): this is an HTTP request like
132. // the page request, so it resolves the SAME session the page route would for that
133. // cookie — a `session.user` a face writes here is what the next document reads.
134. // Before this the face was handed null and a login over the fallback was lost.
135. // AN OUTWARD EMIT RAISED UNDER IT RIDES BACK IN THE ANSWER: there is no
136. // connection to push to, so the frames a face raised for the CALLER are
137. // collected while it runs and shipped in the ack as `emits`, which the client
138. // half delivers before it resolves the emit. The audience fan-out to the other
139. // connections of that user is the same walk it always was.
140. routes[] = { pattern = '/__hl/emit' framework = true function = (route, req) => {
141. if (req.method != 'POST') { return notFound(req.path) }
142. let s = sessions.resolve(req.headers['cookie'] != null ? req.headers['cookie'] : req.headers['Cookie'])
143. let fresh = s == null
144. if (fresh) { s = sessions.mint() }
145. // the session travels in a MEMBER, not an argument: a call argument is a copy,
146. // an instance inside it included, and a copied session loses the face's write
147. postSession = s
148. postHost = hostOf(req.headers['host'])
149. postHeaders = requestHeaders(req.headers)
150. let res = new Response(inbound(null, JSON.parse(req.body)), { headers = { 'Content-Type' = 'application/json; charset=utf-8' } })
151. if (fresh) { res.headers['Set-Cookie'] = sessions.cookieHeader(s.id) }
152. return res
153. } }
154. // A FILE IN AN EMIT TRAVELS OVER HTTP (ticket #94, creator 2026-09-25): the client half
155. // sends each file of an `emit server …` here, in parts, before the emit itself; the emit's
156. // frame then names the upload, and `inbound` hands the face the file in its place.
157. // POST /__hl/upload { name, type, size, q, n } → { id, have } (an upload; see uploadRequest)
158. // POST /__hl/upload?id=&at= one part, raw → { have } (appended when `at` is what arrived so far)
159. // GET /__hl/upload?id= → { have } (after a dropped connection)
160. // An upload belongs to the session of the cookie that started it, and only an emit
161. // of that session can claim it. A part cut short by a dropped connection keeps what
162. // arrived; the client asks for `have` and goes on from there.
163. routes[] = { pattern = '/__hl/upload' framework = true function = (route, req) => {
164. let s = sessions.resolve(req.headers['cookie'] != null ? req.headers['cookie'] : req.headers['Cookie'])
165. let fresh = s == null
166. if (fresh) { s = sessions.mint() }
167. let res = uploadRequest(&s, req)
168. if (fresh) { res.headers['Set-Cookie'] = sessions.cookieHeader(s.id) }
169. return res
170. } }
171. // THE APP'S ONE STYLESHEET — the `styles` file's rules and every mounted
172. // component's `Style { }`, walked in style.hl and cached after the first ask.
173. routes[] = { pattern = styleUrl framework = true function = (route, req) => {
174. return new Response(stylesheet(), { headers = cached(req, 'text/css; charset=utf-8') })
175. } }
176. // THE COMPONENT MODULES ARE ROUTES TOO — the framework's, not the app's: one per
177. // file a page route mounts and per wrapper above it (the graph's `parent`
178. // chain), served at the file's own `.hl` url as the browser's projection. A
179. // browser executes a module by its MIME type, so `text/javascript` at
180. // `/components/home.hl` is a module, and the url is the path the author wrote.
181. // Nothing else is served as a module: a file no page route reaches has no url.
182. // THE LANGUAGE GRAPH, AND THE REALMS ARE THIS PACKAGE'S (creator, 2026-09-12: "the project.hl
183. // defines no realms so the framework just fills them itself"). This file is the server
184. // realm's entrypoint, client.hl beside it the browser's; the app reaches both by
185. // importing hl:web, and the graph follows that reference into the package.
186. graph = hlProject(
187. realms = {
188. server = { entrypoint = './WebFramework.hl' }
189. client = { entrypoint = './client.hl' }
190. }
191. transports = [
192. ['websocket' 'client' 'server']
193. ['websocket' 'server' 'client']
194. ['rest' 'client' 'server']
195. ]
196. )
197. gen = graph.analysisGen // the syntax reflection's handle: the routes below read Views
199. // TWO WEB FRAMEWORKS IN ONE APP IS NOT AN APP (creator, 15 Sep: project.hl switched
200. // to the other framework the repo had then while styles.hl still said 'hl:web/css').
201. // Both packages load, both `on server page` faces answer the same navigation, and
202. // the second answers on a blank instance — a NotCallable deep inside the other framework's dispatch, which
203. // says nothing about the two import rows that caused it. So it is refused HERE,
204. // before anything is served, naming both rows.
205. oneFrameworkOnly()
206. // A VALUE-FORM EMIT HAS ONE ANSWERER (SPEC "An emit ANSWERS", ticket #20): checked here,
207. // before anything is served, because the wire does not say which form an emit was
208. oneAnswererEach()
209. // THE APP'S SETTINGS come from the file that constructed this one when they were not
210. // passed (the archive's `configure()`): `styles`, `audience`, `sessionDir`, the clocks,
211. // `watchMode`, `minify`, `port`
212. cfg = hlConstructor()
213. if (cfg != null) {
214. if (styles == null && cfg.styles != null) { styles = cfg.styles }
215. if (cfg.audience != null && audience.keys().length == 0) { audience = cfg.audience }
216. if (sessionDir == null && cfg.sessionDir != null) { sessionDir = cfg.sessionDir }
217. if (sessionMaxAge == null && cfg.sessionMaxAge != null) { sessionMaxAge = cfg.sessionMaxAge }
218. if (sessionIdle == null && cfg.sessionIdle != null) { sessionIdle = cfg.sessionIdle }
219. if (sweepInterval == null && cfg.sweepInterval != null) { sweepInterval = cfg.sweepInterval }
220. if (sessionCookie == null && cfg.sessionCookie != null) { sessionCookie = cfg.sessionCookie }
221. if (cfg.sessionSecure != null && sessionSecure == false) { sessionSecure = cfg.sessionSecure }
222. if (sessionDomain == null && cfg.sessionDomain != null) { sessionDomain = cfg.sessionDomain }
223. if (cfg.watchMode != null) { watchMode = cfg.watchMode }
224. if (cfg.minify != null) { minify = cfg.minify }
225. if (cfg.port != null) { port = cfg.port }
226. if (offline == null && cfg.offline != null) { offline = cfg.offline }
227. if (offlineFallback == null && cfg.offlineFallback != null) { offlineFallback = cfg.offlineFallback }
228. if (pingEvery == null && cfg.pingEvery != null) { pingEvery = cfg.pingEvery }
229. if (pongWithin == null && cfg.pongWithin != null) { pongWithin = cfg.pongWithin }
230. if (uploadStall == null && cfg.uploadStall != null) { uploadStall = cfg.uploadStall }
231. if (cfg.uploadMax != null) { uploadMax = cfg.uploadMax }
232. }
233. served = {}
234. mounted = []
235. for (r of routes) { if (r.component != null) { mounted[] = keyOf(r.component) } }
236. for (k of mounted) {
237. let key = k
238. // a file the graph does not hold is refused at its route row, below (servedKeys
239. // → routeComponentKey: this walk reads the evaluated table, which has no lines)
240. if (graph.files[key] == null) { key = null }
241. while (key != null) {
242. serveComponent(key)
243. let child = key
244. key = graph.files[key].parent
245. // A PARENT IS A COMPONENT (COMPONENTS §5): one without a View wraps nothing, and
246. // every page under it answered a 500 while the boot said nothing (322 row 13)
247. if (key != null && viewHandle(key) == 0) {
248. 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")
249. }
250. }
251. }
253. // EVERY PACKAGE'S BROWSER HALF IS SERVED, BY ONE RULE. A package whose browser
254. // side is written in this language ships it as `client.hl` beside its
255. // plugin.json; the compiler compiles it like any other file and writes the
256. // importing module `import { … } from "<halfDir>/<pkg>/client.js"`
257. // (js_module.zig browserHalf / browserHalfUrl). Something has to answer that url,
258. // and this is it — for EVERY such package the graph holds, because the rule
259. // belongs to the language and not to one package. hl:web's own half is the first
260. // case of it and no longer a hard-coded route of its own; hl:dnd is the second.
261. //
262. // The graph is the whole guard: a key is here only because the entry's closure
263. // REACHED that package's half through an import, which is the same reason a
264. // component has a module url. A package nothing imports is served nothing.
265. for (gk of graph.files.keys()) {
266. if (gk.startsWith('hl:') && gk.endsWith('/client.hl')) { serveHalf(gk) }
267. }
269. // ---- INSTALLABLE, AND OFFLINE (COMPONENTS §10, tickets #95–#97) ------------------
270. // Two declarations in the app's manifest, and nothing written by hand in the app:
271. // · `appIcons` (with `appTitle`, and optionally `appShortName`, `appThemeColor`,
272. // `appBackgroundColor`, `appManifest`) makes the app INSTALLABLE — the web app
273. // manifest below, linked from every page's head with its apple-touch-icon;
274. // · `offline = [ … ]` makes the pages it names work OFFLINE — the service worker
275. // (worker.hl) that keeps the shell and those pages, and in the client half the
276. // IndexedDB copy of their state and the queue of the emits they make.
277. // An app that declares neither is served nothing of either.
278. offlineKeys = offlinePages()
279. fallbackPattern = offlineFallbackPattern()
280. dataFreeKeys = dataFreePages()
281. queueEvents = offlineKeys != null ? queueable() : []
282. if (installable()) {
283. routes[] = { pattern = manifestUrl framework = true function = (route, req) => {
284. return new Response(JSON.stringify(webManifest()), { headers = { 'Content-Type' = 'application/manifest+json; charset=utf-8' 'Cache-Control' = 'no-cache' } })
285. } }
286. }
287. if (offlineKeys != null) {
288. // the ENTRY SCRIPT is served at the framework's directory, and its scope is the
289. // whole app: `Service-Worker-Allowed` is what lets a script under /__hl/ say so
290. routes[] = { pattern = workerUrl framework = true function = (route, req) => {
291. return new Response(workerEntry(), { headers = { 'Content-Type' = 'text/javascript; charset=utf-8' 'Cache-Control' = 'no-cache' 'Service-Worker-Allowed' = '/' } })
292. } }
293. routes[] = { pattern = halfDir + '/web/worker.js' framework = true function = (route, req) => {
294. return new Response(workerModule(), { headers = cached(req, 'text/javascript; charset=utf-8') })
295. } }
296. }
298. // ---- WHAT THIS APP SERVES, OFF THE ANALYSIS ALONE (mission 315) ----------------
299. // These four are STATIC, so they answer with no instance and without constructing
300. // anything: the compiler evaluates `servedModulesOf(graph)` at BUILD time to bake
301. // each module's text, and this file's own root uses the very same functions at
302. // boot. One definition, two callers — a second derivation would drift, and a
303. // compiled binary would then serve text generated against different urls.
304. //
305. // The seed is the entry's route table AS WRITTEN, read through `hlSyntax`, not
306. // the evaluated `routes` member: evaluating it means constructing the app, and
307. // constructing this class binds a socket. The graph carries the entry's record
308. // since 2026-09-16, which is what makes that readable at all.
310. // A ROUTE'S COMPONENT IS A PAGE: a file without a View answered every request with a 500
311. // ("declares no View", raised without a span) while the boot said nothing (mission 322
312. // row 13). Refused at the row instead.
313. static routePage = (gen, entryKey, valueNode, key) => {
314. 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") }
315. return key
316. }
318. // The key a route row's `component` names: an imported class, or a path string.
319. // Anything else is a located refusal AT THE ROW — never silently unserved.
320. static routeComponentKey = (graph, gen, entryKey, imports, valueNode) => {
321. let v = hlSyntax(gen, entryKey, valueNode)
322. if (v == null) { return null }
323. if (v.tag == 'literal' && v.kind == 'string') {
324. let t = v.text
325. let k = t.startsWith('./') ? t.slice(2) : t
326. // A PATH NO FILE OF THE APP IMPORTS IS NOT IN THE GRAPH: the analysis never read
327. // it, so nothing can be served for it — refused here, at the row, instead of a
328. // null deep in the framework once the server is already up (STATUS §2 item 0)
329. 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`") }
330. return routePage(gen, entryKey, valueNode, k)
331. }
332. if (v.tag == 'identifier') {
333. for (imp of imports) {
334. if (imp.default == v.name && imp.key != null) { return routePage(gen, entryKey, valueNode, imp.key) }
335. }
336. }
337. 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")
338. return null
339. }
341. // does the file at `key` declare a View? (a component, as opposed to a plain class)
342. static hasViewMember = (gen, key) => {
343. for (m of hlMembers(gen, key)) {
344. if (m.name == 'View') { return true }
345. }
346. return false
347. }
349. // `key` and every component it composes, once each — the same walk
350. // `serveComponent` performs, as a function of the graph.
351. static collectServed = (graph, gen, &out, key) => {
352. if (key == null || graph.files[key] == null) { return null }
353. for (k of out) { if (k == key) { return null } }
354. out[] = key
355. for (imp of graph.files[key].imports) {
356. if (imp.default != null && imp.key != null && hasViewMember(gen, imp.key)) {
357. collectServed(graph, gen, out, imp.key)
358. }
359. }
360. return null
361. }
363. // Every key this app answers a module for: each route's component and the wrapper
364. // chain above it, the components those compose, and every package's browser half.
365. static servedKeys = (graph) => {
366. let gen = graph.analysisGen
367. let entryKey = graph.manifest.file
368. let out = []
369. if (entryKey != null && graph.files[entryKey] != null) {
370. let imports = graph.files[entryKey].imports
371. let routesNode = 0
372. for (m of hlMembers(gen, entryKey)) {
373. if (m.name == 'routes') { routesNode = m.node }
374. }
375. if (routesNode != 0) {
376. let arr = hlSyntax(gen, entryKey, routesNode)
377. if (arr != null && arr.tag == 'array_expression') {
378. for (e of arr.elements) {
379. let row = hlSyntax(gen, entryKey, e)
380. if (row != null && row.tag == 'object_expression') {
381. for (pe of row.entries) {
382. let prop = hlSyntax(gen, entryKey, pe)
383. if (prop != null && prop.tag == 'object_property' && prop.key == 'component') {
384. let key = routeComponentKey(graph, gen, entryKey, imports, prop.value)
385. // the wrapper chain above it, deepest last — a page is
386. // served inside whatever wraps it
387. let k = key
388. while (k != null) {
389. collectServed(graph, gen, out, k)
390. k = graph.files[k] != null ? graph.files[k].parent : null
391. }
392. }
393. }
394. }
395. }
396. }
397. }
398. }
399. return out
400. }
402. // EVERY PACKAGE'S BROWSER HALF, BY ONE RULE — a package whose browser side is
403. // written in this language ships it as `client.hl`, the compiler writes
404. // `<halfDir>/<pkg>/client.js` into every importing module, and something has to
405. // answer that url. The graph is the whole guard: a key is here only because the
406. // entry's closure reached that package.
407. //
408. // SEPARATE FROM `servedKeys` ON PURPOSE: a half gets a ROUTE but is not a module
409. // url of this app, so it is not in the map `hlJs` is handed. That asymmetry is
410. // the existing `serveHalf`/`serveComponent` split, stated rather than inherited
411. // by accident — measured 2026-09-16, when folding the two together made the
412. // analysis set one key wider than the route walk's.
413. static packageHalfKeys = (graph) => {
414. let out = []
415. for (gk of graph.files.keys()) {
416. if (gk.startsWith('hl:') && gk.endsWith('/client.hl')) { out[] = gk }
417. }
418. return out
419. }
421. // The browser realm's NAME, off the graph — the declared realm whose entrypoint
422. // is this framework's client half. Static, so the compiler can ask it too.
423. static clientRealmOf = (graph) => {
424. for (name of graph.realms.keys()) {
425. if (graph.realms[name].entrypoint == 'hl:web/client.hl') { return name }
426. }
427. return null
428. }
430. // EVERY MODULE THIS APP SERVES, COMPILED — what a native binary answers `hlJs`
431. // with (mission 315). The emitter needs the runtime specifier, the browser
432. // realm and the served-url map; all three are functions of the analysis, so the
433. // whole map is, and the COMPILER can build it without an instance.
434. //
435. // `minify` is NOT: it is an app setting bound at construction, and the analysis
436. // cannot evaluate a construction. The value used is recorded beside each
437. // module so a binary asked for a different one refuses at the call instead of
438. // answering text generated the other way.
439. // HOW THE APP ASKED FOR ITS MODULES. A build bakes ONE form of every module and
440. // a binary answering the other form would be different bytes, so the build must
441. // read the app's own answer — and the app writes it where it configures the
442. // framework: `new WebFramework(… minify = true …)` in the manifest. The analysis
443. // carries a construction's named arguments, so this is a READ of the same syntax
444. // `servedKeys` reads for the routes, not a second declaration.
445. //
446. // A COMPUTED `minify` IS NOT READ HERE, and nothing is guessed from it: a build
447. // cannot evaluate an expression the running app has not reached yet. Such an app
448. // bakes the unminified form, exactly as every app did before this, and if it
449. // then asks for the other form at run time the binary says so at the request —
450. // "this binary carries the module compiled the other way", located, which is
451. // the refusal that already exists and the one measured on the creator's social
452. // app (2026-09-17). Writing the literal in the manifest is what removes it.
453. static manifestMinify = (graph) => {
454. let gen = graph.analysisGen
455. let key = graph.manifest.file
456. if (key == null || graph.files[key] == null) { return false }
457. for (m of hlMembers(gen, key)) {
458. let s = hlSyntax(gen, key, m.node)
459. if (s != null && s.tag == 'new_expression' && s.named != null) {
460. for (h of s.named) {
461. let p = hlSyntax(gen, key, h)
462. if (p != null && p.tag == 'object_property' && p.key == 'minify') {
463. let v = hlSyntax(gen, key, p.value)
464. if (v != null && v.tag == 'literal' && v.kind == 'boolean') { return v.text == 'true' }
465. }
466. }
467. }
468. }
469. return false
470. }
472. static bakeModules = (graph) => {
473. let realm = clientRealmOf(graph)
474. let served = servedModulesOf(graph)
475. let min = manifestMinify(graph)
476. let out = {}
477. for (k of servedKeys(graph)) {
478. if (graph.files[k] != null) {
479. let p = graph.files[k].path
480. out[p] = {
481. text = hlJs(p, min, runtimeSpec, realm, served)
482. minify = min
483. runtime = runtimeSpec
484. realm = realm
485. }
486. }
487. }
488. // EVERY PACKAGE HALF TOO. The root walk above serves `<halfDir>/<pkg>/client.js`
489. // for every `hl:<pkg>/client.hl` the graph holds, and a compiled binary answers
490. // from BAKED text alone — so a bake that skipped them served the page and then
491. // 404'd on the module the page imports, leaving the client half of the app
492. // dead with nothing reported (measured on projects/framework, 2026-09-16).
493. // Same rule, same list, one loop later: what the server routes, the build bakes.
494. // AN OFFLINE APP'S SERVICE WORKER MODULE (COMPONENTS §10), under its own path
495. if (manifestOffline(graph)) {
496. let wp = workerPathOf(graph)
497. out[wp] = {
498. text = hlJs(wp, min, runtimeSpec, realm, served)
499. minify = min
500. runtime = runtimeSpec
501. realm = realm
502. }
503. }
504. for (gk of graph.files.keys()) {
505. if (gk.startsWith('hl:') && gk.endsWith('/client.hl') && graph.files[gk] != null) {
506. let hp = graph.files[gk].path
507. if (out[hp] == null) {
508. out[hp] = {
509. text = hlJs(hp, min, runtimeSpec, realm, served)
510. minify = min
511. runtime = runtimeSpec
512. realm = realm
513. }
514. }
515. }
516. }
517. return out
518. }
520. // file path → the url this server answers its module at. What `hlJs` is handed,
521. // and what the compiler bakes against.
522. static servedModulesOf = (graph) => {
523. let out = {}
524. for (k of servedKeys(graph)) {
525. if (graph.files[k] != null) { out[graph.files[k].path] = '/' + k + buildMark }
526. }
527. return out
528. }
530. // ONE PACKAGE HALF'S ROUTE. It is a FUNCTION and not the body of the loop above
531. // because the url's route closure must hold THIS key: a `let` in a loop body is
532. // one binding the closures share, so every route built that way would serve the
533. // last package's half (measured 2026-09-14 — both /__hl/web/client.js and
534. // /__hl/dnd/client.js answered with hl:web's module). A parameter is a fresh
535. // binding per call, which is the same reason serveComponent below is a function.
536. serveHalf(key) {
537. routes[] = { pattern = halfUrl(key.slice(3, key.length - 10)) framework = true function = (route, req) => { return serveHl('/' + key, req) } }
538. return null
539. }
541. // a mounted file's module route, and the routes of the components it composes
542. // (an import with a View), recursively — off the graph, once each
543. serveComponent(key) {
544. if (served[key] != null) { return null }
545. served[key] = true
546. routes[] = { pattern = modulePath(key) framework = true function = (route, req) => { return serveHl(req.path, req) } }
547. for (imp of graph.files[key].imports) {
548. if (imp.default != null && imp.key != null && viewHandle(imp.key) != 0) { serveComponent(imp.key) }
549. }
550. return null
551. }
553. // THE PROJECT DIRECTORY: this file lives in a package, so the app's directory is read
554. // off a file that is the app's — the first route component's key against its path
555. root = projectRoot()
556. view = new HlwView
557. css = new HlwCss(minify = minify, view = view)
558. compiler = new HlwCompile
559. sessions = new HlwSessions(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 : '')
560. sessions.open()
561. // THE STYLES FILE IS NAMED AT BOOT, not at the first request for the stylesheet: a value
562. // that names no file, or a file the graph does not hold, is the app's mistake and the
563. // app does not start with it (ticket #12)
564. if (styles != null) {
565. 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)) }
566. 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`") }
567. }
568. // the whole tree, nothing excluded: dot directories (the session store) are skipped by
569. // the walker's own rule, and a custom store inside the tree is the app's choice to pay for
570. if (watchMode) { __native("eventloop.register", watch(root), "hlFileChanged") }
571. sheetText = null // the stylesheet, walked once at the first request for it
572. router = new HlwRouter(routes = routes)
573. trees = {} // key → the View tree, built once
574. slotAt = {} // key → where its View places its one `slot`
575. styleNames = {} // key → the rule names of the file's Style, off the syntax
576. styleRefs = {} // key → [{ tag rule }] the View wrote
577. styleTags = {} // key → the element names this file's View renders
578. styleIds = {} // key → the literal `id` values this file's View writes (R3)
579. staticHolders = {} // key → an instance of a file whose statics another file imports
580. modules = {} // key → the browser module (JavaScript text), compiled once at boot
581. buildHash = null // the hash of everything this build serves, in every cached url (build())
582. workerCompiled = null // the service worker's module as compiled (offline apps only, workerText())
583. shipped = {} // key → the module as served: its build marks replaced with the hash
584. servedUrls = null // file path → the url this server answers its module at, for hlJs
585. runtime = hlJsRuntime() // the runtime library every module imports as "./hl-runtime.js"
586. peers = {} // connection key → the WsClient, while it is open
587. peerSession = {} // connection key → its session, from the tab's `hello` (null = anonymous)
588. peerHost = {} // connection key → the host its upgrade request named (null = none sent)
589. peerHeaders = {} // connection key → its upgrade request's headers (requestHeaders)
590. peerMounts = {} // connection key → the component keys the tab has mounted
591. peerParams = {} // connection key → the route params the tab's shell and page were mounted with
592. // SESSIONS (web/sessions.hl): named by the cookie, at the page request and at the
593. // socket's handshake alike. Nothing about a session ever reaches page script.
594. sending = null // the WsClient whose inbound emit is being handled — the peer
595. // an outward emit reaches, and null under the POST fallback
596. // THE POST FALLBACK'S PEER IS ITS OWN ANSWER. While a face dispatched over
597. // `POST /__hl/emit` runs, `posting` is true and every outward emit meant for the
598. // CALLER is appended here instead of pushed; `inbound` ships the list in the ack.
599. Boolean posting = false
600. postEmits = []
601. postSession = null // the cookie's session of the POST being dispatched
602. postHost = null // the host of the POST being dispatched
603. faceHost = null // the host of the carrier whose inbound emit is being dispatched
604. postHeaders = null // the headers of the POST being dispatched (requestHeaders)
605. faceHeaders = null // the headers of the carrier whose inbound emit is being dispatched
606. // EXACTLY ONCE (COMPONENTS §10): a queued emit carries a stable id `q`, and the ids handled
607. // are kept per session, the last `handledKept` of them (Session.handled). A connection
608. // with no session keeps its ids here, in one list under the same bound.
609. Number handledKept = 200
610. anonHandled = []
611. // WHAT A KEPT ID WAS ANSWERED (ticket #107). An emit in flight when its socket closed
612. // is sent again with its id, and its caller is still waiting — for a page, say. The
613. // first delivery's ack went out on the dead socket, so the repeat is answered from
614. // here: `answers[session id + ' ' + q]` is that ack as sent (its `i` replaced), or
615. // `running` while the first delivery has not finished, which answers the repeat
616. // `later` and the client asks again. In memory, the last `handledKept` of them: a
617. // repeat comes seconds after the first try, and a restart loses nothing a live peer
618. // still waits for but the ack, which is then plain `ok`, as before.
619. answers = {}
620. answerKeys = []
621. uploads = {} // 'u' + upload id → { sid, name, type, size, have, parts, at, key }: a file on its way in (ticket #94)
622. uploadKeys = {} // 'k' + session id + ' ' + q + ' ' + n → the upload id the n-th file of emit q went up under
623. uploadParts = {} // 'u' + id + ':' + n → the n-th part as it arrived, a Bytes
625. // ONE PORT, TWO CARRIERS. hl:http1's WebSocket engine answers the Upgrade
626. // inline on the port this server already bound, so `websocket` and `rest` are
627. // the same listener — which is why the manifest can declare both for the same
628. // direction and this file needs no second server.
629. // EVERY VIEW IS BUILT AT BOOT, not at the first request for its route: a View that
630. // reads a name its file declares nowhere (checkRead) is the app's mistake, and the
631. // app does not start with it — the port is bound on the line below this pass.
632. // THE TWO DERIVATIONS MUST AGREE (mission 315). `served` is built above from the
633. // EVALUATED route table; `servedKeys(graph)` derives the same set from the
634. // analysis alone, and the compiler bakes each module's text against the second.
635. // If they ever disagree the binary would serve modules generated against urls
636. // this server does not answer, so the disagreement is a refusal, here, at boot.
637. for (k of servedKeys(graph)) {
638. if (served[k] == null) {
639. hlError('hl:web: the analysis says this app serves ' + k + ', the route walk did not — the two derivations of the served set disagree')
640. }
641. }
642. for (k of served.keys()) {
643. let seen = false
644. for (a of servedKeys(graph)) { if (a == k) { seen = true } }
645. if (seen == false) {
646. let why = ''
647. for (imp of graph.files[k] != null ? [] : []) { why = why }
648. hlError('hl:web: the route walk serves ' + k + ', the analysis did not — the two derivations of the served set disagree')
649. }
650. }
651. for (k of served.keys()) { if (viewHandle(k) != 0) { tree(k) } }
652. // A COMPONENT-REFERENCE CYCLE IS REFUSED HERE (COMPONENTS §12): a View that renders
653. // itself, directly or through another, is a mount that never ends — it overflowed the
654. // stack at the first request and the server died of a segfault with nothing said
655. // (mission 322 row 1).
656. acyclic = {}
657. for (k of served.keys()) { if (viewHandle(k) != 0) { referenceCycle(k, [], []) } }
658. // …and a page a shell wraps is placed at the shell's slot, inside its body: a page whose
659. // root is `body` there emitted a second, nested <body> (mission 322 row 5)
660. for (k of mounted) {
661. if (graph.files[k] != null && graph.files[k].parent != null && viewHandle(k) != 0 && bodyRooted(k)) {
662. 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 { … }`)")
663. }
664. }
665. // THE SHEET IS WALKED AT BOOT, so the rules it drops are listed at boot (COMPONENTS §4,
666. // css.hl's own header): walked at the first request for it, a dead rule was listed only
667. // once some browser had asked, and a boot log said nothing (mission 322 row 11)
668. stylesheet()
669. // EVERY SERVED MODULE IS COMPILED AT BOOT: a free name in a View handler is a located
670. // compile error (COMPONENTS §6b), and compiled at the first request for the module it
671. // was a 500 behind a page that had already answered 200 (mission 322 row 14)
672. for (k of served.keys()) { module(k) }
674. // THE INTERFACE IS THE OPERATOR'S (ticket #24), on the ladder graph.zig's OperatorBind
675. // states: the constructor's `host` > HL_HOST (the binary fills it from HOST) > the
676. // manifest's > 0.0.0.0. Binding the default regardless put an app meant to sit behind
677. // a proxy on every interface of the machine.
678. if (host == null) { host = env('HL_HOST') }
679. if (host == null && cfg != null && cfg.host != null) { host = cfg.host }
680. if (host == null) { host = '0.0.0.0' }
681. // A --PORT AFTER THE ENTRY OUTRANKS THE APP'S OWN PORT (creator ruling
682. // 2026-09-27), but `port` ITSELF CANNOT SAY SO: the reference app passes an
683. // explicit `port = …` to `new WebFramework(…)` (server.hl, computed from
684. // HL_FW_PORT so a test run can sit beside a developer's own instance), which
685. // PINS the member for the whole construction (SPEC.md "The file root is the
686. // constructor" — "a root assignment to [a pinned] property… is a no-op").
687. // `port = port_arg` below was exactly that no-op: `hybriel server.hl
688. // --port=11499` still bound 44333, server.hl's own default, because this
689. // line's write never landed. `boundPort`, a plain local nothing ever pins,
690. // carries the actual ladder instead — CLI argument, else the (possibly
691. // pinned) member, else HL_PORT, else 8080 — and IS what binds and what the
692. // boot line names.
693. let port_arg = portArgument()
694. let boundPort = port_arg
695. if (boundPort == null) { boundPort = port }
696. if (boundPort == null && env('HL_PORT') != null) { boundPort = toNumber(env('HL_PORT')) }
697. if (boundPort == null) { boundPort = 8080 }
698. http = new NativeWebSocketServer(port = boundPort, host = host)
699. echo 'framework listening on ' + boundPort
700. module('web/client.hl')
702. // ---- the browser's modules: compiled IN PROCESS, served from memory --------------
703. // The JavaScript target is this binary's own function (hlJs), the same one `--js`
704. // runs from the command line. No child process, no build directory.
705. //
706. // THE CLIENT is compiled at boot — every page needs it, and it carries the View
707. // and the Router with it (one module, three classes). A COMPONENT is compiled ON
708. // DEMAND, at the request for its own `.hl` url, and kept: a route nobody visits
709. // costs nothing, and the browser asks for a component's module the first time it
710. // mounts one.
711. //
712. // THE TABLE THE EMITTER WRITES IS DROPPED. `hlJs` puts each file's members,
713. // handlers and methods — every node of every initializer, with the names it reads —
714. // into the module, because the old hl:web's browser half reduces that table on every boot.
715. // This framework asked the same questions at COMPILE time and wrote the answers into
716. // the component's own statements, so the table is dead weight in the page: 58 KB of
717. // syntax on the reference app's home page alone. What the framework SERVES is its own
718. // text, so it leaves that statement out; the language is not asked to change, and
719. // The old hl:web kept its table untouched.
720. // THE TABLE STATEMENT'S NAME in this module: `hlTablesDef`, or in a compact module the
721. // alias its import clause gives it (`hlTablesDef as _51`). Each statement stands at the
722. // start of its own line, which is how it is found — an alias alone is a suffix of other
723. // names (`$_51(` is a compiler temporary).
724. tablesCall(text) {
725. let alias = text.indexOf('hlTablesDef as ')
726. if (alias < 0) { return newline + 'hlTablesDef(' }
727. let first = alias + 15
728. let stop = first
729. while (stop < text.length && text[stop] != ',' && text[stop] != '}') { stop = stop + 1 }
730. return newline + text.slice(first, stop) + '('
731. }
733. // the `fns` of the file's own table — the first table statement the module carries is
734. // the file's; the ones after it are the classes it bundles
735. tableFns(text) {
736. let at = text.indexOf(tablesCall(text))
737. if (at < 0) { return [] }
738. let open = text.indexOf('{', at)
739. let end = text.indexOf(');', at)
740. if (open < 0 || end < 0) { return [] }
741. let t = JSON.parse(text.slice(open, end))
742. return t.fns == null ? [] : t.fns
743. }
745. withoutTables(text) {
746. // one per FILE the module carries — the client half bundles three classes. A compact
747. // module calls it by its alias, and was served with every table until ticket #98's
748. // follow-up: 50 KB and more of syntax on a minified app's page
749. let call = tablesCall(text)
750. let out = text
751. let at = out.indexOf(call)
752. while (at >= 0) {
753. let end = out.indexOf(');', at)
754. if (end < 0) { return out }
755. // the newline before it stays: it ends the statement above
756. out = out.slice(0, at + 1) + out.slice(end + 2)
757. at = out.indexOf(call)
758. }
759. return out
760. }
762. // THE APP RUNS ON ONE WEB FRAMEWORK. Which packages are frameworks is READ OFF THE
763. // GRAPH and not off a list this file keeps: a package the app's entry reached that
764. // holds a `WebFramework.hl` is one. hl:dnd, hl:http1 and every other package an app
765. // imports hold none and are untouched by this.
766. //
767. // The refusal names the ROW of each import, because the mistake IS an import line —
768. // a sub-file import (`'hl:web/css'`) counts as much as the package itself, which is
769. // exactly the case that made it: a lone braced import of a stylesheet helper puts the
770. // whole package into the graph, and with it a second navigation face.
771. oneFrameworkOnly() {
772. let frameworks = {}
773. for (gk of graph.files.keys()) {
774. if (gk.startsWith('hl:') && gk.endsWith('/WebFramework.hl')) { frameworks[gk.slice(0, gk.length - 16)] = true }
775. }
776. if (frameworks.keys().length < 2) { return null }
777. // the first row of the app's OWN files that reached each package
778. let sites = {}
779. for (k of graph.files.keys()) {
780. if (!k.startsWith('hl:')) {
781. for (imp of graph.files[k].imports) {
782. for (pkg of frameworks.keys()) {
783. if (sites[pkg] == null && (imp.source == pkg || imp.source.startsWith(pkg + '/'))) {
784. sites[pkg] = { key = k; node = imp.node; where = k + ':' + imp.line + ':' + imp.col + " imports '" + imp.source + "'" }
785. }
786. }
787. }
788. }
789. }
790. let said = ''
791. for (pkg of frameworks.keys()) {
792. if (said != '') { said = said + ', and ' }
793. if (sites[pkg] == null) { said = said + "'" + pkg + "' (reached through a package, not from a file of the app)" }
794. else { said = said + sites[pkg].where }
795. }
796. 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.'
797. // THE CARET GOES ON ONE OF THE ROWS, and the sentence names them all: two
798. // import lines are equally the mistake, and a diagnostic can only underline one.
799. for (pkg of frameworks.keys()) {
800. if (sites[pkg] != null) { hlSourceError(gen, sites[pkg].key, sites[pkg].node, msg) }
801. }
802. hlError(msg)
803. return null
804. }
806. // ONE ANSWERER PER VALUE-FORM EMIT. SPEC: "if more than one class in the destination
807. // realm declares a non-tap handler for the event, the VALUE form is refused at the emit
808. // site naming both. As a statement it stays a broadcast and every handler still fires."
809. // The statement form is what `inbound` does — every face runs. The value form cannot be
810. // told apart on the wire, so every `x = emit server ev()` the app's files hold is read
811. // off the analysis here, and one whose event two files answer is refused at its site,
812. // naming both, before anything is served. Until ticket #20 both faces ran and the first
813. // answer was taken in silence.
814. oneAnswererEach() {
815. let realm = serverRealm()
816. for (k of graph.files.keys()) {
817. if (!k.startsWith('hl:')) {
818. for (e of hlEvents(gen, k).emits) {
819. if (e.value == true && e.realm == realm) {
820. let owners = facesOf(e.event)
821. if (owners.length > 1) {
822. let named = ''
823. for (o of owners) { named = named == '' ? o : named + ' and ' + o }
824. 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)"
825. hlSourceError(gen, k, e.node, msg)
826. hlError(msg)
827. }
828. }
829. }
830. }
831. }
832. return null
833. }
835. // WHAT THIS SERVER SERVES AS A MODULE OF ITS OWN, by the file's path (mission 314
836. // rule 0). Handed to `hlJs`, it is what turns `import PostCard from './post_card.hl'`
837. // into an ES import of `/components/post_card.hl` instead of PostCard's whole class
838. // text copied into the importing module — EditHistory's class shipped three times on
839. // the social demo's home page before this. The urls are THIS file's (`moduleUrl`);
840. // the compiler invents none, and a file this server does not answer for is inlined
841. // exactly as it always was.
842. servedModules() {
843. if (servedUrls == null) {
844. let out = {}
845. for (k of served.keys()) { out[pathOf(k)] = modulePath(k) + buildMark }
846. servedUrls = out
847. }
848. return servedUrls
849. }
851. // A key the graph holds no file for is answered `null`, and the caller makes
852. // that a 404: a file the entry's closure never referenced is not part of this
853. // app, which is what keeps this from being a read of any path a url asks for.
854. module(key) {
855. if (modules[key] == null) {
856. let f = graph.files[key]
857. if (f == null) { return null }
858. // THE BROWSER GETS THE BROWSER'S PROJECTION, and nothing else. hlJs's
859. // fourth argument is the realm the module is produced for: a handler
860. // written `on server …` is not emitted at all, and a member whose
861. // initializer reaches a name the browser does not have is declared
862. // without one, for this server to lay over the instance with the state
863. // it already ships. The realm NAME comes off the manifest (clientRealm()
864. // above), never a literal — a project names its own realms.
865. let text = hlJs(f.path, minify, runtimeSpec, clientRealm(), servedModules())
866. // AND THE COMPILE STEP'S OWN OUTPUT BESIDE IT (mission 313): a component with a
867. // View carries, after its class, the paint statements this framework compiled
868. // from that View — one per bound spot, with its read written in (compile.hl).
869. // The browser calls them instead of walking the tree at paint time. Text
870. // produced here and served from memory like the module itself; nothing is
871. // written to disk and no JavaScript file lives under plugins/.
872. // THE FUNCTION VALUES' SITES are the one part of that table the browser still
873. // needs (tickets #98, #99): the compile step turns them into write sets
874. let fns = tableFns(text)
875. text = withoutTables(text)
876. if (viewHandle(key) != 0) { text = text + newline + compiler.module(gen, key, tree(key), fns) }
877. modules[key] = text
878. }
879. return modules[key]
880. }
882. // the file the graph knows under this key — the graph carries every file's own path
883. pathOf(key) {
884. let f = graph.files[key]
885. if (f == null) { hlError('the graph holds no file ' + key + ' — nothing referenced it from the entry') }
886. return f.path
887. }
889. // THE BROWSER'S REALM, off the manifest: the realm whose declared entrypoint is
890. // this framework's client half. The framework's own two files ARE the two
891. // realms' entrypoints, so this is a lookup and never a guess.
892. clientRealm() {
893. for (name of graph.realms.keys()) {
894. if (graph.realms[name].entrypoint == 'hl:web/client.hl') { return name }
895. }
896. 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')
897. }
899. // THIS realm, off the graph: the declared realm whose entrypoint REACHES this
900. // file (the app's entry imports it). A face names it, and so does the refusal
901. // when nothing answers.
902. serverRealm() {
903. let mine = graph.files['hl:web/WebFramework.hl'].realms
904. if (mine.length == 1) { return mine[0] }
905. 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')
906. }
908. // the app's directory: a route component is the app's file, its key project-relative
909. projectRoot() {
910. for (r of routes) {
911. if (r.component != null) { return rootOf(keyOf(r.component)) }
912. }
913. // AN APP OF FUNCTION ROUTES ONLY (ticket #19) has no component to read it off, and
914. // needs no other: the manifest is the app's file too, and the graph knows its key
915. if (graph.manifest.file != null && graph.files[graph.manifest.file] != null) { return rootOf(graph.manifest.file) }
916. 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')
917. }
919. // a project-relative key against its absolute path: what is left is the project's directory
920. rootOf(key) {
921. let path = pathOf(key)
922. // A COMPILED BINARY'S PATH IS ITS KEY (mission 318): it carries no
923. // build directory, so the file's path and its key are the same
924. // string and the root is the process's own directory. The
925. // interpreter's path is the script's absolute one, and the key is
926. // its tail — the root is what stands before it.
927. if (path == key) { return '.' }
928. return path.slice(0, path.length - key.length - 1)
929. }
931. // THE KEY OF A FILE THE APP NAMED — as the class it imported (`component = SortList`,
932. // `styles = Styles`: the import is the guarantee the graph reached it) or as a path
933. // ('./components/home.hl'). A class knows its file (`file(cls)`), and the graph knows
934. // the file's key.
935. keyOf(named) {
936. if (hlTypeName(named) == 'Class') {
937. let path = file(named)
938. for (k of graph.files.keys()) {
939. if (graph.files[k].path == path) { return k }
940. }
941. hlError('hl:web: the class at ' + path + ' is not in the project graph — import it from the app\'s entry')
942. }
943. // ANYTHING ELSE NAMES NO FILE (ticket #12): `styles = {}` booted and every request
944. // for the stylesheet was then a NotCallable on this line, with no line of the app's
945. 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)) }
946. if (named.startsWith('./')) { return named.slice(2) }
947. return named
948. }
950. // ---- the View tree: the member's syntax, reflected into plain hybrids ----------
951. viewHandle(key) {
952. for (m of hlMembers(gen, key)) {
953. if (m.name == 'View') { return m.node }
954. }
955. return 0
956. }
958. tree(key) {
959. if (trees[key] != null) { return trees[key] }
960. let handle = viewHandle(key)
961. if (handle == 0) { hlError('component ' + key + ' declares no View') }
962. let v = hlSyntax(gen, key, handle)
963. let nodes = []
964. for (h of v.entries) {
965. let n = node(key, h, [], false, [])
966. if (n != null) { nodes.push(n) }
967. }
968. trees[key] = nodes
969. return nodes
970. }
972. // one entry of a hybrid literal → a tree node (null for an attribute: the
973. // element that owns it reads it)
974. node(key, handle, path, inFor, rows) {
975. let n = hlSyntax(gen, key, handle)
976. if (n == null) { return null }
977. if (n.tag == 'object_property') {
978. let v = hlSyntax(gen, key, n.value)
979. if (v.tag == 'object_expression') {
980. let childKey = componentKeyOf(key, n.key)
981. if (childKey != null) { return component(key, n.key, childKey, v, v, path, inFor, rows) }
982. return element(key, n.key, v, path, inFor, rows)
983. }
984. return null
985. }
986. if (n.tag == 'literal') { return { k = 'text'; text = n.text; kind = n.kind; } }
987. if (n.tag == 'identifier') {
988. // A BARE CAPITALISED REFERENCE IS A COMPOSITION WITH AN EMPTY FILL (§12:
989. // "`Name { }` is the same reference as bare `Name`"). It is not a read, so it
990. // is answered before the read rules below refuse the name.
991. let bareKey = componentKeyOf(key, n.name)
992. if (bareKey != null) { return component(key, n.name, bareKey, null, n, path, inFor, rows) }
993. if (n.name == 'slot') { oneSlot(key, n) }
994. // AN IMPORTED STATIC IN A VIEW IS FOLDED (the archive did the same at build):
995. // `h1 { siteTitle }` with `import { siteTitle } from '../store.hl'` is not a
996. // member of this class, it is a constant of another file — read off that
997. // file's class once, here, and written into the tree as text
998. return nameRead(key, n.name, rows, n)
999. }
1000. if (n.tag == 'view_for') {
1001. // `for (row of list) { … }` — the list is a member (or a row field), the
1002. // body's entries are rendered once per entry with `row` bound to it
1003. let body = hlSyntax(gen, key, n.body)
1004. let children = []
1005. // THE ROW VARIABLE IS IN SCOPE INSIDE THE BODY, and nowhere else: the list is
1006. // read in the scope that stands around the `for`
1007. let list = ref(key, n.list, rows)
1008. let inner = rows.slice(0)
1009. inner.push(n.varName)
1010. for (h of body.entries) {
1011. let c = node(key, h, path, true, inner)
1012. if (c != null) { children.push(c) }
1013. }
1014. // THE SITE, as every element node carries one: the id the module's tables
1015. // file this `for`'s row under, so the browser reads what the list depends
1016. // on from the compiler instead of guessing it off `list.name`.
1017. return { k = 'for'; row = n.varName; list = list; body = children; site = baseName(pathOf(key)) + ':' + n.line + ':' + n.col; }
1018. }
1019. if (n.tag == 'view_if') {
1020. let then = []
1021. let cons = hlSyntax(gen, key, n.consequent)
1022. for (h of cons.entries) {
1023. let c = node(key, h, path, inFor, rows)
1024. if (c != null) { then.push(c) }
1025. }
1026. let other = []
1027. let alt = hlSyntax(gen, key, n.alternate) // null when there is no else
1028. if (alt != null) {
1029. if (alt.tag == 'view_if') {
1030. other.push(node(key, n.alternate, path, inFor, rows))
1031. } else {
1032. for (h of alt.entries) {
1033. let c = node(key, h, path, inFor, rows)
1034. if (c != null) { other.push(c) }
1035. }
1036. }
1037. }
1038. // A BRANCH CONDITION IS A READ (COMPONENTS: a member or a loop path).
1039. // Anything else came back null here and the branch rendered nothing, on the
1040. // server and after hydration, with no word said (ticket #17: `if (!flag)`).
1041. let cond = ref(key, n.condition, rows)
1042. if (cond == null) {
1043. let c = hlSyntax(gen, key, n.condition)
1044. 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)`")
1045. }
1046. return { k = 'if'; cond = cond; then = then; other = other; site = baseName(pathOf(key)) + ':' + n.line + ':' + n.col; }
1047. }
1048. if (n.tag == 'member_expression') {
1049. // `p.title` — a field path off a member or a row variable
1050. let r = ref(key, handle, rows)
1051. if (r != null) { return r }
1052. }
1053. if (n.tag == 'binary_expression' || n.tag == 'unary_expression' || n.tag == 'conditional_expression') {
1054. // AN EXPRESSION IN A VIEW: its tree, and the names it reads (what repaints it)
1055. let names = []
1056. let x = exprTree(key, handle, rows, &names)
1057. return { k = 'expr'; x = x; names = names; }
1058. }
1059. if (n.tag == 'on_statement') {
1060. // a DOM event handled by the literal that carries it: the browser finds the
1061. // literal in the instance's View by the path of keys and fires the event at it
1062. // THE SITE IS THE HANDLER'S ID: the tables file this handler's write set
1063. // under it, and the browser repaints exactly those members when it runs.
1064. return { k = 'on'; event = n.event; site = baseName(pathOf(key)) + ':' + n.line + ':' + n.col; }
1065. }
1066. return { k = 'other'; tag = n.tag; }
1067. }
1069. // A COMPONENT HAS EXACTLY ONE SLOT (COMPONENTS §2 table, §12): a second one rendered the
1070. // child a second time, with no word said (mission 322 row 4)
1071. oneSlot(key, n) {
1072. let here = baseName(pathOf(key)) + ':' + n.line + ':' + n.col
1073. if (slotAt[key] != null) {
1074. 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")
1075. }
1076. slotAt[key] = here
1077. return null
1078. }
1080. isMember(key, name) {
1081. for (m of hlMembers(gen, key)) { if (m.name == name) { return true } }
1082. return false
1083. }
1085. // THE READ OF A BARE NAME IN A VIEW — wherever the name stands. A text child, an
1086. // attribute's value and a reference-site binding are ONE lookup with ONE refusal:
1087. //
1088. // a `for` row variable standing around the read → read at render, from the row
1089. // a member of this file → read at render, from the instance
1090. // a name this file imports by BRACE → a STATIC of another file:
1091. // constant-folded here, at build
1092. // anything else → the located refusal (checkRead)
1093. //
1094. // An ATTRIBUTE used to skip the middle two and record every name as a member read,
1095. // so `a { href = brandHref }` on a braced import asked the instance for a member it
1096. // does not have and the renderer raised error.UndefinedProperty with view.hl's line
1097. // and nothing of the app's — while the same name as a TEXT CHILD rendered fine
1098. // (creator, routger migration W8). A read is a read; where it stands decides
1099. // nothing about what it names.
1100. nameRead(key, name, rows, at) {
1101. if (rows != null && rows.includes(name)) { return { k = 'member'; name = name; } }
1102. if (isMember(key, name)) { return { k = 'member'; name = name; } }
1103. // A BRACED IMPORT FOLDS EVEN WHEN ITS VALUE IS NULL: the name resolved, so the
1104. // read is answered here and never reaches the instance (a null static used to
1105. // fall through to a member read and raise the same UndefinedProperty).
1106. if (importsName(key, name)) {
1107. let folded = importedStatic(key, name)
1108. // THE VALUE AS WELL AS THE TEXT: an attribute and a text child want the text,
1109. // and a reference binding wants the value the author's file declared (§12)
1110. return { k = 'text'; text = folded == null ? '' : '' + folded; kind = 'folded'; value = folded; }
1111. }
1112. checkRead(key, name, rows, at)
1113. return { k = 'member'; name = name; }
1114. }
1116. // A VIEW READS ONLY WHAT ITS FILE DECLARES. A name that is neither a member of
1117. // this class, nor a static it imports by brace, nor a `for` row variable standing
1118. // around this read, is a typo or a missing declaration — refused HERE, at the
1119. // build of the tree (boot), naming the file and the line, instead of a 500 out of
1120. // the renderer with the language's UndefinedProperty and no line of the app's.
1121. checkRead(key, name, rows, n) {
1122. if (rows != null && rows.includes(name)) { return null }
1123. if (isMember(key, name)) { return null }
1124. if (importsName(key, name)) { return null }
1125. let hint = name == 'session' ? "`session = null` to receive the connection's session" : name == 'host' ? "`host = null` to receive the request's host" : name == 'headers' ? "`headers = null` to receive the request's headers" : "`" + name + " = null`"
1126. 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")
1127. }
1129. // does this file import that name by brace from another file?
1130. \* `--port=N` or `--port N` among the program's arguments, or null. *\
1131. portArgument() {
1132. let given = args()
1133. let i = 0
1134. while (i < given.length) {
1135. let a = given[i]
1136. let text = null
1137. if (a.startsWith('--port=')) {
1138. text = a.slice(7)
1139. } else if (a == '--port' && i + 1 < given.length) {
1140. text = given[i + 1]
1141. }
1142. if (text != null) {
1143. let digits = text.length > 0 && text.length <= 5
1144. let b = toBytes(text)
1145. let k = 0
1146. while (k < b.length) {
1147. if (b[k] < 48 || b[k] > 57) { digits = false }
1148. k = k + 1
1149. }
1150. if (!digits || toNumber(text) > 65535) {
1151. hlError("hl:web: invalid --port value '" + text + "' — a port is a number 0-65535")
1152. }
1153. return toNumber(text)
1154. }
1155. i = i + 1
1156. }
1157. return null
1158. }
1160. importsName(key, name) {
1161. for (imp of graph.files[key].imports) {
1162. if (imp.key != null && imp.names.includes(name)) { return true }
1163. }
1164. return false
1165. }
1167. // the value of a static this file imports by brace from another .hl file, or null —
1168. // read off an instance of that file (a class value takes no computed index, an
1169. // instance does; the file is constructed once, its statics were evaluated at load)
1170. importedStatic(key, name) {
1171. for (imp of graph.files[key].imports) {
1172. if (imp.key != null && imp.names.includes(name)) {
1173. if (staticHolders[imp.key] == null) { staticHolders[imp.key] = construct(imp.key, constructionArgs(imp.key, {}, anonSession(), null, null)) }
1174. return staticHolders[imp.key][name]
1175. }
1176. }
1177. return null
1178. }
1180. // THE TREE OF A VIEW EXPRESSION: operators, literals and reads — evaluated by view.hl's
1181. // `evalExpr`, with the language's own operators. `names` collects the members it reads.
1182. exprTree(key, handle, rows, &names) {
1183. let n = hlSyntax(gen, key, handle)
1184. if (n.tag == 'literal') { return { k = 'text'; text = n.text; kind = n.kind; } }
1185. if (n.tag == 'identifier') {
1186. let r = nameRead(key, n.name, rows, n)
1187. if (r.k == 'member' && !names.includes(r.name)) { names.push(r.name) }
1188. return r
1189. }
1190. if (n.tag == 'member_expression' && !n.computed) {
1191. let r = ref(key, handle, rows)
1192. if (r != null) {
1193. if (!names.includes(r.name)) { names.push(r.name) }
1194. return r
1195. }
1196. }
1197. if (n.tag == 'binary_expression') {
1198. return { k = 'bin'; op = n.operator; l = exprTree(key, n.left, rows, &names); r = exprTree(key, n.right, rows, &names); }
1199. }
1200. if (n.tag == 'unary_expression') {
1201. return { k = 'un'; op = n.operator; x = exprTree(key, n.operand, rows, &names); }
1202. }
1203. if (n.tag == 'conditional_expression') {
1204. return { k = 'cond'; c = exprTree(key, n.condition, rows, &names); a = exprTree(key, n.consequent, rows, &names); b = exprTree(key, n.alternate, rows, &names); }
1205. }
1206. hlError("hl:web: " + baseName(pathOf(key)) + ':' + n.line + ':' + n.col + " — a View expression holds names, literals, member paths and operators; a " + n.tag + " is none of those — declare it at the root of " + baseName(pathOf(key)) + " and write its name")
1207. }
1209. // a READ in the View: a member (`title`), or a field path (`p.title`) whose root
1210. // is a member or a `for` row variable — the client decides which at render time
1211. ref(key, handle, rows) {
1212. let n = hlSyntax(gen, key, handle)
1213. if (n.tag == 'identifier') { checkRead(key, n.name, rows, n) return { k = 'member'; name = n.name; } }
1214. // A LIST WRITTEN IN PLACE (`for (n of [1, 2])`) is a literal, read as its value: the
1215. // same folded 'text' node a folded static is, so every reader takes it the way it takes
1216. // that one. Its entries are literals — anything else has no value before a read.
1217. if (n.tag == 'array_expression') {
1218. let items = []
1219. for (e of n.elements) {
1220. let el = hlSyntax(gen, key, e)
1221. if (el == null || el.tag != 'literal') {
1222. hlError("hl:web: " + baseName(pathOf(key)) + ':' + n.line + ':' + n.col + " — a list written in a View can hold literals only; declare it as a member to loop over anything else")
1223. }
1224. items.push(view.literalValue(el.kind, el.text))
1225. }
1226. return { k = 'text'; text = ''; kind = 'folded'; value = items; }
1227. }
1228. if (n.tag == 'member_expression' && !n.computed) {
1229. let obj = hlSyntax(gen, key, n.object)
1230. let prop = hlSyntax(gen, key, n.property)
1231. if (obj.tag == 'identifier') { checkRead(key, obj.name, rows, obj) return { k = 'field'; name = obj.name; path = [prop.name]; } }
1232. let inner = ref(key, n.object, rows)
1233. if (inner != null && inner.k == 'field') {
1234. let path = inner.path.slice(0)
1235. path.push(prop.name)
1236. return { k = 'field'; name = inner.name; path = path; }
1237. }
1238. }
1239. return null
1240. }
1242. // THE COMPOSED CHILD: an entry named after a class the file imports, whose file
1243. // has a View. `Child { count = count on done(v) { … } }` — the entries are the
1244. // BINDINGS (host values handed to the child's construction as named arguments)
1245. // and the reference-site handlers. The graph says which name is which file.
1246. componentKeyOf(key, name) {
1247. for (imp of graph.files[key].imports) {
1248. if (imp.default == name && imp.key != null && viewHandle(imp.key) != 0) { return imp.key }
1249. }
1250. return null
1251. }
1253. // THE REFERENCE'S SITE IS IN ITS PATH. A path of class names alone made two
1254. // references of one class under one parent (`body/Card` twice) the SAME node key,
1255. // so both collapsed onto one mount and one of the two fills was lost. A reference
1256. // is a construction: each one is its own mount, so each one is its own path.
1257. componentStep(cls, at) {
1258. return cls + '@' + at.line + ':' + at.col
1259. }
1261. // is this entry a `Style.rule` reference? (the `Style` of THIS file, by name)
1262. styleRef(key, e) {
1263. let obj = hlSyntax(gen, key, e.object)
1264. return obj.tag == 'identifier' && obj.name == 'Style'
1265. }
1267. // THE REFERENCE'S POSITIONAL SIGNATURE (§12: "a reference is a construction, so its
1268. // POSITIONAL entries bind to the class's declared properties in declaration order —
1269. // the same rule `new X(a, b)` follows").
1270. //
1271. // MEASURED, not guessed (2026-09-13, this worker): `new X(a, b, …)` fills the class's
1272. // root PROPERTY DECLARATIONS in SOURCE ORDER, one slot each — `on` handlers and
1273. // methods take no slot, and `hlMembers` returns exactly that list in exactly that
1274. // order, so the tree builder reads the signature straight off it. Three of those
1275. // declarations are not properties of the COMPOSITION and are left out here:
1276. //
1277. // `View` and `Style` — what the component renders and paints WITH, not what it is
1278. // constructed from. The language does give them a slot (a
1279. // bare `new` binds them), but §12 says `Card { "text" }` with
1280. // no declared property takes its text as FILL, and a
1281. // component always declares a View: counting it would make
1282. // the positional-literal fill unreachable in every component
1283. // there is.
1284. // `slot` — the late-bound child, not state (§12); and with the fill
1285. // rendered where the child places it the two readings emit
1286. // the same HTML anyway.
1287. // every `static` — a static belongs to the CLASS (§12 build-time constants), so
1288. // a reference cannot seed one for every other reference.
1289. //
1290. // A NAMED assignment does NOT free its slot — measured: `new Q('n1', beta = 'B', 'n2')`
1291. // puts 'n2' in the SECOND declaration and 'B' in beta. It is applied AFTER the
1292. // positional ones and wins, which is why the positional bindings are emitted first
1293. // below. (COMPONENTS.md:711 reads "a property the reference also assigns by name is
1294. // not in the signature"; the interpreter says otherwise and the parenthetical in the
1295. // same line — "named is applied after positional; the name wins, as in `new`" — is
1296. // what this follows.)
1297. positionalSignature(key) {
1298. let out = []
1299. for (m of hlMembers(gen, key)) {
1300. if (!m.isStatic && m.name != 'View' && m.name != 'Style' && m.name != 'slot') { out.push(m.name) }
1301. }
1302. return out
1303. }
1305. component(key, cls, childKey, v, at, path, inFor, rows) {
1306. let bindings = []
1307. let positional = []
1308. let ons = []
1309. let fill = []
1310. let here = path.slice(0)
1311. here.push(componentStep(cls, at))
1312. let sig = positionalSignature(childKey)
1313. let taken = 0
1314. if (v != null) {
1315. for (h of v.entries) {
1316. let e = hlSyntax(gen, key, h)
1317. if (e.tag == 'object_property') {
1318. let val = hlSyntax(gen, key, e.value)
1319. // A BINDING NAMES A DECLARED MEMBER OF THE CHILD (COMPONENTS §12): the value
1320. // otherwise went into the construction and nowhere, with no word said
1321. // (mission 322 row 12). An element entry is the fill, not a binding.
1322. if (val.tag != 'object_expression' && !isMember(childKey, e.key)) {
1323. 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(', '))
1324. }
1325. // A LITERAL ON A REFERENCE KEEPS ITS TYPE (§12 "typed, not stringified"):
1326. // the binding carries the literal's KIND, and `view.refValue` turns the
1327. // pair into the value the child's member is given. Written as text alone,
1328. // `Level2 { n = 1 }` handed the child the String "1" and `n * 97` refused
1329. // (measured 2026-09-14, demo-nested wall 3).
1330. if (val.tag == 'literal') { bindings.push({ name = e.key; text = val.text; kind = val.kind; }) }
1331. else if (val.tag == 'identifier') {
1332. // a binding is a read at the reference site, so it is the same lookup
1333. let r = nameRead(key, val.name, rows, val)
1334. // …and a folded static crosses as its VALUE, for the same reason
1335. if (r.k == 'text') { bindings.push({ name = e.key; text = r.text; kind = 'folded'; value = r.value; }) }
1336. else { bindings.push({ name = e.key; member = val.name; }) }
1337. }
1338. else if (val.tag == 'member_expression') { bindings.push({ name = e.key; ref = ref(key, e.value, rows); }) }
1339. else {
1340. // `Card { span { … } }` — an element entry is not a binding, it is the FILL
1341. let c = node(key, h, here, inFor, rows)
1342. // …and an EXPRESSION is neither, so it is refused rather than dropped:
1343. // the same rule an attribute follows (mission 312 wall 4).
1344. if (c == null) {
1345. 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`")
1346. }
1347. fill.push(c)
1348. }
1349. } else if (e.tag == 'on_statement') {
1350. // A HANDLER WRITTEN ON A REFERENCE IS THE HOST'S, bound on the child's ROOT
1351. // element. The reference is a literal of THIS file's View, so its behaviour
1352. // is minted from THIS file's site and its body reaches this file through the
1353. // owner rule — the same path an element's own handler takes. The child's own
1354. // handler on that element is not replaced: both are listeners on one element
1355. // and both run, the child's first, because it was bound when the child's tree
1356. // was claimed. (Until 2026-09-13 the event was collected here and dropped: a
1357. // reference with `on submit` never bound, and a form submitted natively.)
1358. // …AND ITS SITE, because the tables file this handler's write set
1359. // under it: the browser repaints exactly what it wrote (mission 309).
1360. ons.push({ event = e.event; site = baseName(pathOf(key)) + ':' + e.line + ':' + e.col; })
1361. } else if (e.tag == 'member_expression' && !e.computed && styleRef(key, e)) {
1362. // a `Style.rule` written on a reference: the reference renders no element
1363. // of its own, so there is nothing for the class to land on (§12)
1364. 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")
1365. } else {
1366. // AN ORDERED ENTRY. A literal or a read is the next declared property's
1367. // value while the signature has room — `Button { "SD" }` is `Button
1368. // { label = "SD" }` — and everything else, plus everything that EXCEEDS
1369. // the signature, is the FILL: a fragment of THIS file's View, with its
1370. // reads, its handlers and its `for` rows (§12 "host content").
1371. let c = node(key, h, here, inFor, rows)
1372. if (c != null) {
1373. if (taken < sig.length && (c.k == 'text' || c.k == 'member' || c.k == 'field')) {
1374. // the same rule as the named form above: a literal keeps its kind and a
1375. // folded static crosses as its value
1376. if (c.k == 'text') { positional.push({ name = sig[taken]; text = c.text; kind = c.kind; value = c.value; }) }
1377. else if (c.k == 'member') { positional.push({ name = sig[taken]; member = c.name; }) }
1378. else { positional.push({ name = sig[taken]; ref = c; }) }
1379. taken = taken + 1
1380. } else { fill.push(c) }
1381. }
1382. }
1383. }
1384. }
1385. // THE NAMED ASSIGNMENTS COME LAST, so the name wins over the positional entry that
1386. // landed on the same property (measured: that is what `new` does)
1387. let allBindings = []
1388. for (b of positional) { allBindings.push(b) }
1389. for (b of bindings) { allBindings.push(b) }
1390. bindings = allBindings
1391. // FILLING WHAT PLACES NO SLOT IS A LOCATED ERROR (§12): the child would drop the
1392. // content silently, which is exactly the bug this rule was written for.
1393. if (fill.length > 0 && !isMember(childKey, 'slot')) {
1394. 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")
1395. }
1396. let classes = []
1397. if (styleRules(key).includes('#' + cls) && !viewIds(key).includes(cls)) {
1398. classes.push(view.localClass(key))
1399. for (t of rootTags(childKey)) { noteRef(key, t, '#' + cls) }
1400. }
1401. // THE NODE NAMES ITS CHILD, it does not carry it. What the browser needs to build
1402. // a child the server never mounted — the module url and the View tree — stands
1403. // ONCE in the seed's blueprint table, keyed by this `key` (blueprintsIn below).
1404. // The node used to carry that pair itself, and only when it stood inside a `for`:
1405. // a child deeper in a minted child's own tree therefore had nothing to build from
1406. // and was silently missing after a push (a comment card's like button and its
1407. // edit history, creator's social app, 2026-09-13).
1408. // THE REFERENCE'S OWN SITE: `file:line:col` of the reference literal, the id the
1409. // JavaScript target mints ITS behaviour class under — what a handler written on
1410. // the reference is built from, in the host's frame (client.hl bindRefOns)
1411. let site = baseName(pathOf(key)) + ':' + at.line + ':' + at.col
1412. return { k = 'component'; cls = cls; key = childKey; path = here; bindings = bindings; ons = ons; classes = classes; row = inFor; fill = fill; site = site; }
1413. }
1415. // ---- Style, the View side (§4, as the archive did it) --------------------------
1416. // The tree builder writes the class on the element and REPORTS what it wrote
1417. // (`styleRefs[key]` = [{ tag rule }]) and the element names it rendered
1418. // (`styleTags[key]`); web/style.hl spells the selectors from those. Three ways
1419. // a rule reaches an element: `Style.rule` written on it (class = the tag-prefix
1420. // strip of the rule name), a `#rule` local of this file matching the element by
1421. // NAME (class = this file's four-character class; `#Child` matches a composed
1422. // child's root elements), and — decided in style.hl, no class — a rule named
1423. // like an element of this file's own View.
1424. styleRules(key) {
1425. if (styleNames[key] != null) { return styleNames[key] }
1426. let names = []
1427. for (m of hlMembers(gen, key)) {
1428. if (m.name == 'Style') {
1429. let v = hlSyntax(gen, key, m.node)
1430. for (h of v.entries) {
1431. let e = hlSyntax(gen, key, h)
1432. if (e.tag == 'object_property' && !names.includes(e.key)) { names.push(e.key) }
1433. }
1434. }
1435. }
1436. styleNames[key] = names
1437. return names
1438. }
1440. noteRef(key, tag, rule) {
1441. if (styleRefs[key] == null) { styleRefs[key] = [] }
1442. for (r of styleRefs[key]) { if (r.tag == tag && r.rule == rule) { return null } }
1443. styleRefs[key].push({ tag = tag; rule = rule; })
1444. return null
1445. }
1447. noteTag(key, tag) {
1448. if (styleTags[key] == null) { styleTags[key] = [] }
1449. if (!styleTags[key].includes(tag)) { styleTags[key].push(tag) }
1450. return null
1451. }
1453. // `#name` IS AN ID WHEN THE VIEW HAS ONE (creator's ruling, ticket #51 / R3): a
1454. // `#name` rule targets the element with `id = 'name'` if this file's View writes
1455. // that id, and is the file-local class of the elements named `name` otherwise. The
1456. // ids are read off the View's SYNTAX before the tree is built, because an element
1457. // named `name` may stand before the element that carries the id. Only a literal id
1458. // counts — a member-bound one has no value until render. A component reference's
1459. // own `id = …` is a binding for the child, not an element of this View; its fill is.
1460. viewIds(key) {
1461. if (styleIds[key] != null) { return styleIds[key] }
1462. let out = []
1463. let handle = viewHandle(key)
1464. if (handle != 0) { idsIn(key, hlSyntax(gen, key, handle), false, &out) }
1465. styleIds[key] = out
1466. return out
1467. }
1469. idsIn(key, block, isRef, &out) {
1470. if (block == null || block.entries == null) { return null }
1471. for (h of block.entries) {
1472. let n = hlSyntax(gen, key, h)
1473. if (n != null && n.tag == 'object_property') {
1474. let v = hlSyntax(gen, key, n.value)
1475. if (v.tag == 'object_expression') { idsIn(key, v, componentKeyOf(key, n.key) != null, &out) }
1476. else if (!isRef && n.key == 'id' && v.tag == 'literal' && !out.includes(v.text)) { out.push(v.text) }
1477. } else if (n != null && n.tag == 'view_for') {
1478. idsIn(key, hlSyntax(gen, key, n.body), false, &out)
1479. } else if (n != null && n.tag == 'view_if') {
1480. idsIn(key, hlSyntax(gen, key, n.consequent), false, &out)
1481. let alt = hlSyntax(gen, key, n.alternate)
1482. if (alt != null && alt.tag == 'view_if') { idsIn(key, { entries = [n.alternate] }, false, &out) }
1483. else { idsIn(key, alt, false, &out) }
1484. }
1485. }
1486. return null
1487. }
1489. // the root element tags of a component's tree (a composed child under `#Child`)
1490. rootTags(key) {
1491. let out = []
1492. for (n of tree(key)) { if (n.k == 'el' && !out.includes(n.tag)) { out.push(n.tag) } }
1493. return out
1494. }
1496. baseName(p) {
1497. let i = p.lastIndexOf('/')
1498. return i < 0 ? p : p.slice(i + 1)
1499. }
1501. element(key, tag, v, path, inFor, rows) {
1502. let attrs = []
1503. let children = []
1504. let here = path.slice(0)
1505. here.push(tag)
1506. let domTag = view.domTag(tag)
1507. // `body { }` IS THE PAGE'S BODY, and only as the View's root (COMPONENTS §6): below
1508. // the root it rendered a second, nested <body> no browser keeps (mission 322 row 5)
1509. if (domTag == 'body' && path.length > 0) {
1510. 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")
1511. }
1512. noteTag(key, tag)
1513. let classes = []
1514. for (h of v.entries) {
1515. let e = hlSyntax(gen, key, h)
1516. let styled = false
1517. if (e.tag == 'member_expression' && !e.computed) {
1518. let obj = hlSyntax(gen, key, e.object)
1519. let prop = hlSyntax(gen, key, e.property)
1520. if (obj.tag == 'identifier' && obj.name == 'Style') {
1521. if (!styleRules(key).includes(prop.name)) { hlError("no Style rule named '" + prop.name + "' in " + key) }
1522. 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") }
1523. let cls = view.kebab(view.className(prop.name, tag)) // the class is kebab-case (creator, 2026-09-12)
1524. if (!classes.includes(cls)) { classes.push(cls) }
1525. noteRef(key, tag, prop.name)
1526. styled = true
1527. }
1528. }
1529. if (styled) {
1530. // a Style reference is not a child
1531. } else if (e.tag == 'object_property') {
1532. let val = hlSyntax(gen, key, e.value)
1533. if (val.tag == 'literal' && view.isBoolAttr(e.key) && val.kind == 'boolean') {
1534. // A BOOLEAN ATTRIBUTE IS ITS PRESENCE (ticket #33): `disabled = true` is the
1535. // attribute, `disabled = false` its absence — decided here, once, for every
1536. // writer of the markup
1537. if (val.text == 'true') { attrs.push({ name = e.key; text = ''; }) }
1538. } else if (val.tag == 'literal') {
1539. attrs.push({ name = e.key; text = val.text; })
1540. } else if (val.tag == 'identifier') {
1541. // THE SAME LOOKUP A TEXT CHILD USES: a folded static becomes the
1542. // attribute's literal text, a member or a row stays a read
1543. let r = nameRead(key, val.name, rows, val)
1544. if (r.k == 'text' && view.isBoolAttr(e.key)) { if (view.boolOn(r.value)) { attrs.push({ name = e.key; text = ''; }) } }
1545. else if (r.k == 'text') { attrs.push({ name = e.key; text = r.text; }) }
1546. else { attrs.push({ name = e.key; member = val.name; }) }
1547. } else if (val.tag == 'member_expression') {
1548. attrs.push({ name = e.key; ref = ref(key, e.value, rows); })
1549. } else {
1550. let c = node(key, h, here, inFor, rows)
1551. // AN EXPRESSION AS AN ATTRIBUTE VALUE IS REFUSED HERE, AND WAS DROPPED IN
1552. // SILENCE (mission 312 wall 4). `span { id = 'L3t' + n }` rendered no `id`
1553. // at all and said nothing — the element came back with empty attributes and
1554. // the author had no line to look at. A View attribute takes a literal, a
1555. // member or a field path; anything else is a member of this file, declared
1556. // at its root. The nested-element form (`div { span { … } }`) is the entry
1557. // whose value is a hybrid, and it is what `node` answers for above.
1558. if (c == null) {
1559. 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`")
1560. }
1561. children.push(c)
1562. }
1563. } else {
1564. let c = node(key, h, here, inFor, rows)
1565. if (c != null) { children.push(c) }
1566. }
1567. }
1568. // a `#tag` LOCAL rule of this file matches this element by name: the file's class
1569. // — unless the View writes `id = 'tag'` somewhere, then the rule is that id's (R3)
1570. if (styleRules(key).includes('#' + tag) && !viewIds(key).includes(tag)) {
1571. let cls = view.localClass(key)
1572. if (!classes.includes(cls)) { classes.push(cls) }
1573. noteRef(key, domTag, '#' + tag)
1574. }
1575. if (classes.length > 0) {
1576. let joined = ''
1577. for (c of classes) { joined = joined == '' ? c : joined + ' ' + c }
1578. let merged = false
1579. for (a of attrs) {
1580. if (a.name == 'class' && a.text != null) { a.text = a.text + ' ' + joined merged = true }
1581. }
1582. if (!merged) { attrs.push({ name = 'class'; text = joined; }) }
1583. }
1584. // (§6 sibling entries: inside the literal `tag` would name the entry just written,
1585. // so the source key is taken before the literal is built)
1586. let srcKey = tag
1587. // THE SITE: `file:line:col` of the literal, the id the JavaScript target mints the
1588. // literal's class under — the browser builds this element's literal from it
1589. // (hlLiteralNew), so a row created after a list changed has a literal too
1590. let site = baseName(pathOf(key)) + ':' + v.line + ':' + v.col
1591. return { k = 'el'; tag = domTag; key = srcKey; path = here; attrs = attrs; children = view.implied(domTag, children, here, site); site = site; }
1592. }
1594. // ---- an instance and its state -------------------------------------------------
1595. // THE ROUTE'S GROUPS ARE THE CONSTRUCTION'S NAMED ARGUMENTS (creator ruling
1596. // 2026-09-12): `:id` is a parameter of the class like any other, set and pinned
1597. // before its root runs, so `_post = db.fetch(id)` on line 1 sees it. Nothing is
1598. // laid over an instance afterwards, and nothing is spelled with a sigil.
1599. construct(key, params) {
1600. return hlLoad(pathOf(key), params)
1601. }
1603. // THE VIEW IS COMPILER OUTPUT, NOT A VALUE — and so, for a render, is the Style.
1604. // This half reads the View's SYNTAX (`tree()` below, through hlSyntax) and never its
1605. // value; `state()` ships neither to the browser; the stylesheet is folded into class
1606. // names at build, by a walk that constructs its OWN instance and reads `Style` there.
1607. // Evaluating them for a render therefore built a behaviour literal per element per
1608. // `for` row, per request, for nobody: half the construction time of a 2000-row
1609. // component, measured 2026-09-14.
1610. //
1611. // The framework says so in the one way the language already offers: it PINS them.
1612. // An explicitly passed construction value outranks every computed default (the
1613. // creator's rule of 2026-07-26), and a pinned member does not compute its default at
1614. // all. No language rule about a View was needed and none was added.
1615. renderArgs(key, args) {
1616. let out = args
1617. if (declares(key, 'View')) { out.View = null }
1618. if (declares(key, 'Style')) { out.Style = null }
1619. return out
1620. }
1622. // does the file-class declare a member of this name?
1623. declares(key, name) {
1624. for (m of hlMembers(gen, key)) { if (m.name == name && !m.isStatic) { return true } }
1625. return false
1626. }
1628. // EVERY SERVER REFERENCE SITE of `key` (compile.hl `derivList`'s `srv`: an initializer
1629. // that calls an imported class) that transitively reads `root` — the same closure
1630. // client.hl's `moved()` walks locally for an ordinary derivation, run here instead
1631. // because a server reference site must never run in the browser (see that file's
1632. // `d.srv` branch). The VALUES come from `state` at the call site, already correct —
1633. // `mount()` just constructed it — this only decides WHICH of its keys belong in
1634. // `sync`, the same as `moved()` decides which of an instance's members to repaint.
1635. serverSyncNames(key, root) {
1636. let list = compiler.tableOf(gen, key).derivations
1637. let moved = [root]
1638. let rounds = 0
1639. let again = true
1640. while (again && rounds <= list.length) {
1641. again = false
1642. rounds = rounds + 1
1643. for (d of list) {
1644. if (!moved.includes(d.name)) {
1645. for (r of compiler.memberNames(d.reads)) {
1646. if (r != d.name && moved.includes(r)) { moved.push(d.name) again = true }
1647. }
1648. }
1649. }
1650. }
1651. let names = []
1652. for (d of list) { if (d.serverSite && d.name != root && moved.includes(d.name)) { names.push(d.name) } }
1653. return names
1654. }
1656. // THE FRAMEWORK'S OWN CONSTRUCTIONS — the sheet walk (a component is constructed to
1657. // read its `Style`), an imported static's holder — happen outside any request, and a
1658. // class's root runs at construction: `me = session.user` there would meet a null,
1659. // which a real render never has (every request carries a session, minted if the
1660. // browser brought none). So they are handed an ANONYMOUS session — nobody logged in,
1661. // never saved — and the root takes its logged-out branch (the creator, 2026-09-13:
1662. // /__hl/app.css was a 500 while the page it styles was 200).
1663. anon = null
1664. anonSession() {
1665. if (anon == null) { anon = new HlwSession(created = now(), seen = now()) }
1666. return anon
1667. }
1669. // THE SESSION AT CONSTRUCTION. A component that declares a member `session` is
1670. // constructed with the connection's session as that named argument — the same
1671. // instance a server face gets as its trailing argument, and nothing ambient: a
1672. // shell reads `me = session.user` at its root on the server, and a reload renders
1673. // logged in (measured by the creator 2026-09-13: the shell rendered logged-out
1674. // after a reload while the faces posted as alice). The browser gets only what a
1675. // page may see of it (`state()` below), never the id the cookie carries.
1676. constructionArgs(key, params, s, host, hdrs) {
1677. let wantsSession = declares(key, 'session')
1678. let wantsHost = declares(key, 'host')
1679. let wantsHeaders = declares(key, 'headers')
1680. if (!wantsSession && !wantsHost && !wantsHeaders) { return params }
1681. let args = {}
1682. for (k of params.keys()) { args[k] = params[k] }
1683. if (wantsSession) { args.session = s }
1684. if (wantsHost) { args.host = host }
1685. if (wantsHeaders) { args.headers = hdrs }
1686. return args
1687. }
1689. // THE HOST AT CONSTRUCTION (ticket #74), by the same rule: a component that declares
1690. // a member `host` is constructed with the host the request named — the `Host`
1691. // header without its port — so an app answering one address per subdomain renders
1692. // the right page on the server. A navigation takes it from ITS carrier: the socket's
1693. // upgrade request, or the POST's own. Null where the request named none, and for the
1694. // framework's own constructions above, which answer no request.
1695. hostOf(header) {
1696. if (header == null || header == '') { return null }
1697. let h = header.trim()
1698. // an IPv6 literal keeps its brackets: `[::1]:8080` is `[::1]`
1699. if (h.startsWith('[')) {
1700. let close = h.indexOf(']')
1701. return close < 0 ? h : h.slice(0, close + 1)
1702. }
1703. let colon = h.indexOf(':')
1704. return colon < 0 ? h : h.slice(0, colon)
1705. }
1707. // THE REQUEST'S HEADERS AT CONSTRUCTION (ticket #105), by the same rule again: a
1708. // component that declares a member `headers` is constructed with the request's
1709. // headers as a hash, every name lowercase — `headers['accept-language']`. A
1710. // navigation takes them from its carrier, as it takes the host: the socket's upgrade
1711. // request, or the POST's own, so they are what this browser sends. The cookie and
1712. // the credentials are LEFT OUT: a member is state, state is shipped to the page, and
1713. // nothing about a session ever reaches page script (`session = null` is the way to
1714. // it). An empty hash where the request named none; null for the framework's own
1715. // constructions, which answer no request.
1716. requestHeaders(raw) {
1717. let out = {}
1718. if (raw == null) { return out }
1719. for (k of raw.keys()) {
1720. let name = k.toLowerCase()
1721. if (name != 'cookie' && name != 'authorization' && name != 'proxy-authorization') { out[name] = raw[k] }
1722. }
1723. return out
1724. }
1726. state(key, page) {
1727. let out = {}
1728. for (m of hlMembers(gen, key)) {
1729. if (m.name != 'View' && m.name != 'Style' && !m.isStatic) {
1730. // A FUNCTION MEMBER IS NOT STATE. JSON has no form for it, and shipping
1731. // it as null would PIN null over the browser's own declaration (a
1732. // construction argument outranks the default) — so it is left out, and
1733. // the browser's instance evaluates `hideBadge = () => { … }` itself.
1734. if (m.name == 'session') {
1735. // the session's PUBLIC part: who is logged in — the id stays on the server
1736. out.session = page.session != null ? { user = page.session.user } : null
1737. } else if (hlTypeName(page[m.name]) != 'Function') { out[m.name] = page[m.name] }
1738. }
1739. }
1740. return out
1741. }
1743. // everything the browser needs about one mounted component — and its children:
1744. // every component node of its tree is a mount of its own, constructed with the
1745. // bindings evaluated against THIS instance, keyed by the node's path
1746. mount(key, params, s, host, hdrs) {
1747. return mountIn(key, params, s, host, hdrs, [])
1748. }
1750. // `chain`: the keys of the mounts above this one — what tells a component that renders
1751. // itself (#111) where its recursion stands
1752. mountIn(key, params, s, host, hdrs, chain) {
1753. let page = construct(key, renderArgs(key, constructionArgs(key, params, s, host, hdrs)))
1754. let line = chain.slice(0)
1755. line.push(key)
1756. let m = { key = key; params = params; view = tree(key); state = state(key, page); page = page; kids = {}; session = s; host = host; headers = hdrs; above = line; }
1757. mountKids(&m, m.view, {}, '', true)
1758. return m
1759. }
1761. // `rowKey` is what tells one row's child from the next one's: the index of every
1762. // enclosing `for` iteration, appended to the component node's path. A component
1763. // outside every `for` has the empty rowKey and keeps the key it always had.
1764. // `standing`: every `if` on the way down took this branch. A branch that does not stand is
1765. // NOT mounted: the browser builds its children itself when the branch comes to stand
1766. // (client `kidAt` mints what the server did not mount, and `bindKids` filed the edge to
1767. // the host's member already). The seed carried every arm's mounts before, and a page of
1768. // many `if`s (demo-markdown) was 450 KB of children nobody saw; a recursive component
1769. // (#111) in an arm that does not stand is the same rule.
1770. // `nodes` and `rows` by reference, as view.hl's walk takes them: nothing here writes
1771. // through either, and each call copied the View subtree and the row (a block with all
1772. // its spans) once per element and per row — 17 M copied nodes, ~5 GB, per load of a
1773. // Markdown child (#127).
1774. mountKids(&m, &nodes, &rows, rowKey, standing) {
1775. for (n of nodes) {
1776. if (n.k == 'component' && !standing) {
1777. // not mounted: see above
1778. } else if (n.k == 'component') {
1779. let args = {}
1780. for (b of n.bindings) {
1781. if (b.text != null) { args[b.name] = view.refValue(b) }
1782. else if (b.member != null) { args[b.name] = view.value({ k = 'member'; name = b.member; }, m.page, rows) }
1783. else if (b.ref != null) { args[b.name] = view.value(b.ref, m.page, rows) }
1784. }
1785. m.kids[view.kidKey(n.path) + rowKey] = mountIn(n.key, args, m.session, m.host, m.headers, m.above)
1786. // THE FILL IS THIS FILE'S FRAGMENT, not the child's: a component standing
1787. // inside it is a child of THIS mount, evaluated in THIS scope
1788. if (n.fill != null) { mountKids(&m, n.fill, rows, rowKey, standing) }
1789. } else if (n.k == 'el') {
1790. mountKids(&m, n.children, rows, rowKey, standing)
1791. } else if (n.k == 'if') {
1792. let taken = view.value(n.cond, m.page, rows)
1793. mountKids(&m, n.then, rows, rowKey, standing && taken)
1794. mountKids(&m, n.other, rows, rowKey, standing && !taken)
1795. } else if (n.k == 'for') {
1796. // ONE MOUNT PER ROW: the row is the scope the bindings are evaluated in,
1797. // so the child is constructed once per entry, with that entry's values
1798. let entries = view.value(n.list, m.page, rows)
1799. if (entries != null) {
1800. let ri = 0
1801. for (entry of entries) {
1802. let inner = rows + {}
1803. inner[n.row] = entry
1804. // THE ROW'S KEY, not its index: a child of a row travels with the
1805. // record it was mounted for (view.rowKey, the one rule the server's
1806. // HTML walk and the browser's region read too)
1807. mountKids(&m, n.body, inner, rowKey + '#' + view.rowKey(entry, ri), standing)
1808. ri = ri + 1
1809. }
1810. }
1811. }
1812. }
1813. return null
1814. }
1816. // the route component and, if it declares one, its wrapping shell.
1817. // THE PARENT IS THE GATE (COMPONENTS §5, creator 2026-08-26): a shell whose render
1818. // places no `slot` — none in its View, or one inside a region that stands false for
1819. // this request — gets no page. The page is then not CONSTRUCTED, not only not shown:
1820. // its root does not run, and nothing of it reaches the document or the seed. The
1821. // shell is built first and rendered to learn that; `placed` is the browser's answer
1822. // when it already has one (a navigation into its own shell, or a region that opened),
1823. // and the server's render is not asked then.
1824. mounts(m, s, host, hdrs, placed) {
1825. let key = keyOf(m.route.component)
1826. let out = { page = null; shell = null; shellHtml = null; }
1827. let w = hlFile(gen, key).wrapper
1828. let open = w == null || placed == true
1829. if (w != null) { out.shell = mount(w, m.params, s, host, hdrs) }
1830. if (w != null && placed == null) {
1831. out.shellHtml = renderOf(out.shell, shellRoot(out.shell), minify ? null : tab, slotMarker)
1832. open = out.shellHtml.indexOf(slotMarker) >= 0
1833. }
1834. if (open) { out.page = mount(key, m.params, s, host, hdrs) }
1835. return out
1836. }
1838. // where the page goes in the shell's first render: the page's HTML replaces it
1839. static slotMarker = '<!--hl:slot-->'
1841. // `body { … }` as the shell's View root IS the page body (COMPONENTS §6): its
1842. // children are rendered into the document's body instead of nesting one
1843. shellRoot(shell) {
1844. let root = shell.view
1845. if (root.length == 1 && root[0].k == 'el' && root[0].tag == 'body') { return root[0].children }
1846. return root
1847. }
1849. // A MOUNT IS NOT ITS TREE. What the browser needs per mount is what makes THIS one
1850. // this one — its key, the route's params, the state the server evaluated, its
1851. // children — while the View tree belongs to the COMPONENT and stands once in the
1852. // seed's blueprint table under the same key. Shipping it per mount put the same tree
1853. // in the payload as many times as the page mounted that component.
1854. ship(&mount) {
1855. let kids = {}
1856. for (k of mount.kids.keys()) { kids[k] = ship(mount.kids[k]) }
1857. return { key = mount.key; params = shipParams(mount.params); state = mount.state; module = moduleUrl(mount.key); kids = kids; }
1858. }
1860. \* A FUNCTION-VALUED BINDING IS NOT SHIPPED — the same rule `state` keeps for a
1861. function MEMBER, for the same reason. A routine a host hands a child
1862. (`PostForm { onPosted = ... }`) has no JSON form, and shipping it as null
1863. would PIN null over the browser's own binding: a construction argument
1864. outranks what the client evaluates. It is left out, and the browser binds it
1865. from the host instance when it builds the mirror, exactly as it does for a
1866. member. Until mission 320 it rode the wire as null because `JSON.stringify`
1867. invented that null; the language refuses to now, which is what made the lie
1868. visible. *\
1869. shipParams(params) {
1870. let out = {}
1871. for (k of params.keys()) {
1872. if (hlTypeName(params[k]) != 'Function') { out[k] = params[k] }
1873. }
1874. return out
1875. }
1877. // A COMPONENT IS SERVED AT ITS OWN `.hl` URL. A browser executes a module by
1878. // its MIME type, never by its extension, so `text/javascript` on
1879. // `/components/home.hl` is a module — and the url the page loads is then the
1880. // path the author wrote in the route table, with nothing renamed in between.
1881. // The route that answers it is the APP's (a `function` route in the manifest),
1882. // because where an app serves its modules from is the app's to say.
1883. modulePath(key) {
1884. return '/' + key
1885. }
1887. // the url a module is LOADED at: its path and the build's version (see buildMark)
1888. moduleUrl(key) {
1889. return modulePath(key) + version()
1890. }
1892. // `?v=<hash>`: THE BUILD'S VERSION. The hash is over every text this app serves
1893. // under it — the runtime, each component module and package half as compiled (the
1894. // marks still in them), and the stylesheet — so any change to any of them, a
1895. // new compiler's output included, is a new version. Computed at the first ask and
1896. // again after a watched save; one hash for the whole build, because the modules
1897. // import each other and a per-module hash would have to be in its importers' text.
1898. version() {
1899. if (buildHash == null) {
1900. let all = runtime + stylesheet()
1901. for (k of served.keys()) { all = all + module(k) }
1902. for (k of packageHalfKeys(graph)) { all = all + module(k) }
1903. // AN OFFLINE APP'S WORKER AND MANIFEST ARE PART OF THE BUILD: the worker's entry
1904. // script names this hash, so a changed worker or a changed icon list is a new
1905. // script to the browser, which installs it and drops the old build's cache
1906. if (offlineKeys != null) { all = all + workerText() }
1907. if (installable()) { all = all + JSON.stringify(webManifest()) }
1908. buildHash = sha256(all).slice(0, 16)
1909. }
1910. return '?v=' + buildHash
1911. }
1913. // the headers of a versioned answer: a request naming THIS build's version is cached
1914. // for a year and never revalidated; one naming another (or none) must not be, or a
1915. // cache would keep this build's text under a url the next build reuses
1916. cached(req, type) {
1917. let h = { 'Content-Type' = type }
1918. h['Cache-Control'] = req.query != null && req.query.v == buildHash && buildHash != null ? 'public, max-age=31536000, immutable' : 'no-cache'
1919. return h
1920. }
1922. // A PACKAGE'S BROWSER HALF IS SERVED BESIDE THE RUNTIME. Not a convention this
1923. // file invents: the compiler derives the specifier it writes into every importing
1924. // module from the runtime url it is handed, and for the same reason that url is
1925. // one member here — one url means ONE ES-module instance, and two would be two
1926. // copies of the package's browser state. This is that derivation, on this side.
1927. halfUrl(pkg) {
1928. return halfDir + '/' + pkg + '/client.js'
1929. }
1931. // The module of the `.hl` url a request names — the on-demand half of the
1932. // transpile. The app's function route hands the path here.
1933. serveHl(urlPath, req) {
1934. let key = urlPath.slice(1)
1935. if (shipped[key] == null) {
1936. let js = module(key)
1937. if (js == null) { return notFound(urlPath) }
1938. shipped[key] = js.replaceAll(buildMark, version())
1939. }
1940. return new Response(shipped[key], { headers = cached(req, 'text/javascript; charset=utf-8') })
1941. }
1943. // ---- the stylesheet -------------------------------------------------------------
1944. // A `Style { }` member is an ORDINARY member of the file's class, so its value
1945. // is what a construction produces — the statics it reads already folded, the
1946. // `+` rule merge already the language's. That is the whole input; style.hl does
1947. // the walk. The project's styles file comes first so its global rules stand
1948. // under every component's, then every component this server can mount, in the
1949. // order `served` holds them (the pages and the wrapper chain above them — the
1950. // same set that has a browser module).
1951. stylesheet() {
1952. if (sheetText == null) {
1953. css.gen = gen
1954. css.view = view
1955. let files = []
1956. if (styles != null) {
1957. // THE STYLES FILE: root members, its inherits first. It has to be in the
1958. // graph (the app imports it) — its rules are read in authored order off
1959. // the syntax and their values off the constructed instance.
1960. let tokenKeys = [] // the token files already walked
1961. for (sk of inheritChain(keyOf(styles))) {
1962. 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") }
1963. // A TOKEN FILE the styles file member-imports (`import { dark } from './tokens.hl'`,
1964. // there `static dark = var('#123')`) is walked BEFORE it, so its var() tokens are
1965. // named and written into :root first. Before ticket #39 part 2 only the chain's own
1966. // non-static members were named, and every imported token was an unknown id: a 500
1967. // "a css variable is used before any styles file declared it". (The architect's
1968. // patch from mission 021 of the tickets app, taken upstream.)
1969. for (tk of tokenFilesOf(sk)) {
1970. if (!tokenKeys.includes(tk)) {
1971. tokenKeys.push(tk)
1972. files.push({ key = tk; cls = graph.files[tk].class; rules = tokenRules(tk); aliases = []; refs = []; tags = []; hasView = false; isStyles = true; })
1973. }
1974. }
1975. let inst = hlLoad(pathOf(sk), {})
1976. let rules = []
1977. let own = {}
1978. for (m of hlMembers(gen, sk)) {
1979. // D32: `mode = 'static'` makes EVERY root member static (the file
1980. // directive's whole point — a token file need not repeat the keyword),
1981. // so `m.isStatic` cannot be what decides whether a member is a css
1982. // rule/token: that used to exclude every rule of a mode='static' file
1983. // and emit none of them. What a rule IS — a var() token or a block —
1984. // is a question about its VALUE, which css.hl already answers below and
1985. // in sheet() (isBlock / isVar); static or not, a plain-scalar helper
1986. // constant folds into nothing there regardless.
1987. if (m.node != 0) {
1988. let v = hlSyntax(gen, sk, m.node)
1989. // a merged rule (`a = b + { … }`) is a block too (css.entriesOf)
1990. 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]))); })
1991. own[m.name] = true
1992. }
1993. }
1994. // EACH FILE OF THE CHAIN IS ITS OWN INSTANCE, so a token it INHERITS is a second
1995. // CssVar with its own id: `body { color = dark }` in the child held an id the
1996. // walker never named (ticket #39 part 1). The inherited tokens are registered
1997. // under their names as ALIASES — named, never written into :root a second time.
1998. // (D32, as above: `css.isVar` alone decides it, not `m.isStatic`.)
1999. let aliases = []
2000. for (pk of inheritChain(sk)) {

Only the first lines are shown.