xbintsc 0.5.22 → 0.5.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (391) hide show
  1. package/AGENTS.md +12 -3
  2. package/README.md +46 -11
  3. package/README.zh-CN.md +32 -6
  4. package/dist/scripts/support-matrix.d.ts +18 -0
  5. package/dist/scripts/support-matrix.js +141 -0
  6. package/dist/scripts/support-matrix.js.map +1 -0
  7. package/dist/src/ast/common.d.ts +2 -2
  8. package/dist/src/ast/declarations.d.ts +7 -1
  9. package/dist/src/ast/expressions.d.ts +5 -0
  10. package/dist/src/ast/kinds.d.ts +2 -0
  11. package/dist/src/ast/kinds.js +2 -0
  12. package/dist/src/ast/kinds.js.map +1 -1
  13. package/dist/src/binder/binder.d.ts +2 -1
  14. package/dist/src/binder/binder.js +2 -0
  15. package/dist/src/binder/binder.js.map +1 -1
  16. package/dist/src/binder/declarations.d.ts +9 -0
  17. package/dist/src/binder/declarations.js +64 -0
  18. package/dist/src/binder/declarations.js.map +1 -1
  19. package/dist/src/binder/references.js +85 -3
  20. package/dist/src/binder/references.js.map +1 -1
  21. package/dist/src/binder/types.d.ts +32 -0
  22. package/dist/src/binder/types.js.map +1 -1
  23. package/dist/src/canonical.d.ts +29 -0
  24. package/dist/src/canonical.js +35 -0
  25. package/dist/src/canonical.js.map +1 -0
  26. package/dist/src/checker/assignability.d.ts +13 -0
  27. package/dist/src/checker/assignability.js +146 -0
  28. package/dist/src/checker/assignability.js.map +1 -0
  29. package/dist/src/checker/calls.d.ts +13 -0
  30. package/dist/src/checker/calls.js +127 -0
  31. package/dist/src/checker/calls.js.map +1 -0
  32. package/dist/src/checker/checker.d.ts +26 -0
  33. package/dist/src/checker/checker.js +31 -0
  34. package/dist/src/checker/checker.js.map +1 -0
  35. package/dist/src/checker/declarations.d.ts +9 -0
  36. package/dist/src/checker/declarations.js +15 -0
  37. package/dist/src/checker/declarations.js.map +1 -0
  38. package/dist/src/checker/flow.d.ts +21 -0
  39. package/dist/src/checker/flow.js +241 -0
  40. package/dist/src/checker/flow.js.map +1 -0
  41. package/dist/src/checker/globals.d.ts +9 -0
  42. package/dist/src/checker/globals.js +29 -0
  43. package/dist/src/checker/globals.js.map +1 -0
  44. package/dist/src/checker/source.d.ts +38 -0
  45. package/dist/src/checker/source.js +48 -0
  46. package/dist/src/checker/source.js.map +1 -0
  47. package/dist/src/checker/type-infer.d.ts +18 -0
  48. package/dist/src/checker/type-infer.js +173 -0
  49. package/dist/src/checker/type-infer.js.map +1 -0
  50. package/dist/src/checker/type-model.d.ts +73 -0
  51. package/dist/src/checker/type-model.js +151 -0
  52. package/dist/src/checker/type-model.js.map +1 -0
  53. package/dist/src/checker/type-system.d.ts +58 -0
  54. package/dist/src/checker/type-system.js +569 -0
  55. package/dist/src/checker/type-system.js.map +1 -0
  56. package/dist/src/checker/typecheck-types.d.ts +22 -0
  57. package/dist/src/checker/typecheck-types.js +109 -0
  58. package/dist/src/checker/typecheck-types.js.map +1 -0
  59. package/dist/src/checker/typecheck.d.ts +62 -0
  60. package/dist/src/checker/typecheck.js +574 -0
  61. package/dist/src/checker/typecheck.js.map +1 -0
  62. package/dist/src/checker/undefined.d.ts +14 -0
  63. package/dist/src/checker/undefined.js +32 -0
  64. package/dist/src/checker/undefined.js.map +1 -0
  65. package/dist/src/checker/walk.d.ts +10 -0
  66. package/dist/src/checker/walk.js +15 -0
  67. package/dist/src/checker/walk.js.map +1 -0
  68. package/dist/src/cli/help.d.ts +7 -0
  69. package/dist/src/cli/help.js +64 -0
  70. package/dist/src/cli/help.js.map +1 -0
  71. package/dist/src/cli/hints.js +13 -1
  72. package/dist/src/cli/hints.js.map +1 -1
  73. package/dist/src/cli/main.js +12 -48
  74. package/dist/src/cli/main.js.map +1 -1
  75. package/dist/src/codegen/generator/calls/access.js +8 -8
  76. package/dist/src/codegen/generator/calls/access.js.map +1 -1
  77. package/dist/src/codegen/generator/calls/invocation.js +9 -4
  78. package/dist/src/codegen/generator/calls/invocation.js.map +1 -1
  79. package/dist/src/codegen/generator/calls/super.d.ts +9 -1
  80. package/dist/src/codegen/generator/calls/super.js +56 -5
  81. package/dist/src/codegen/generator/calls/super.js.map +1 -1
  82. package/dist/src/codegen/generator/context.d.ts +13 -2
  83. package/dist/src/codegen/generator/context.js +25 -19
  84. package/dist/src/codegen/generator/context.js.map +1 -1
  85. package/dist/src/codegen/generator/debug.js +2 -1
  86. package/dist/src/codegen/generator/debug.js.map +1 -1
  87. package/dist/src/codegen/generator/expressions/primary.d.ts +4 -1
  88. package/dist/src/codegen/generator/expressions/primary.js +68 -8
  89. package/dist/src/codegen/generator/expressions/primary.js.map +1 -1
  90. package/dist/src/codegen/generator/generator.js +11 -1
  91. package/dist/src/codegen/generator/generator.js.map +1 -1
  92. package/dist/src/codegen/generator/module.d.ts +2 -0
  93. package/dist/src/codegen/generator/module.js +62 -26
  94. package/dist/src/codegen/generator/module.js.map +1 -1
  95. package/dist/src/codegen/generator/state.d.ts +11 -1
  96. package/dist/src/codegen/generator/state.js.map +1 -1
  97. package/dist/src/codegen/generator/statements/variables.js +20 -3
  98. package/dist/src/codegen/generator/statements/variables.js.map +1 -1
  99. package/dist/src/codegen/generator/tables.d.ts +2 -0
  100. package/dist/src/codegen/generator/tables.js +4 -0
  101. package/dist/src/codegen/generator/tables.js.map +1 -1
  102. package/dist/src/driver/build-key.d.ts +2 -0
  103. package/dist/src/driver/build-key.js +1 -0
  104. package/dist/src/driver/build-key.js.map +1 -1
  105. package/dist/src/driver/bundler/graph.js +5 -1
  106. package/dist/src/driver/bundler/graph.js.map +1 -1
  107. package/dist/src/driver/bundler/merge.js +16 -1
  108. package/dist/src/driver/bundler/merge.js.map +1 -1
  109. package/dist/src/driver/bundler/types.d.ts +12 -0
  110. package/dist/src/driver/compiler.d.ts +1 -1
  111. package/dist/src/driver/compiler.js +4 -0
  112. package/dist/src/driver/compiler.js.map +1 -1
  113. package/dist/src/driver/fingerprint.js +2 -1
  114. package/dist/src/driver/fingerprint.js.map +1 -1
  115. package/dist/src/driver/frontend.d.ts +8 -6
  116. package/dist/src/driver/frontend.js +4 -0
  117. package/dist/src/driver/frontend.js.map +1 -1
  118. package/dist/src/driver/options.d.ts +6 -0
  119. package/dist/src/driver/version.d.ts +1 -1
  120. package/dist/src/driver/version.js +1 -1
  121. package/dist/src/extensions/catalog.js +2 -1
  122. package/dist/src/extensions/catalog.js.map +1 -1
  123. package/dist/src/extensions/gui/html.js +20 -6
  124. package/dist/src/extensions/gui/html.js.map +1 -1
  125. package/dist/src/extensions/gui/index.js +63 -0
  126. package/dist/src/extensions/gui/index.js.map +1 -1
  127. package/dist/src/extensions/media/index.d.ts +27 -0
  128. package/dist/src/extensions/media/index.js +60 -0
  129. package/dist/src/extensions/media/index.js.map +1 -0
  130. package/dist/src/extensions/registry.d.ts +50 -0
  131. package/dist/src/extensions/registry.js +26 -0
  132. package/dist/src/extensions/registry.js.map +1 -1
  133. package/dist/src/index.d.ts +2 -0
  134. package/dist/src/index.js +2 -0
  135. package/dist/src/index.js.map +1 -1
  136. package/dist/src/parser/declarations/classes.js +7 -0
  137. package/dist/src/parser/declarations/classes.js.map +1 -1
  138. package/dist/src/parser/expressions.js +14 -1
  139. package/dist/src/parser/expressions.js.map +1 -1
  140. package/dist/src/parser/literals.js +6 -2
  141. package/dist/src/parser/literals.js.map +1 -1
  142. package/dist/tests/binder/binder.test.js +29 -0
  143. package/dist/tests/binder/binder.test.js.map +1 -1
  144. package/dist/tests/canonical.test.d.ts +1 -0
  145. package/dist/tests/canonical.test.js +19 -0
  146. package/dist/tests/canonical.test.js.map +1 -0
  147. package/dist/tests/checker/checker.test.d.ts +1 -0
  148. package/dist/tests/checker/checker.test.js +245 -0
  149. package/dist/tests/checker/checker.test.js.map +1 -0
  150. package/dist/tests/cli/check.test.js +20 -0
  151. package/dist/tests/cli/check.test.js.map +1 -1
  152. package/dist/tests/cli/hints.test.js +15 -0
  153. package/dist/tests/cli/hints.test.js.map +1 -1
  154. package/dist/tests/cli/process.test.js +12 -0
  155. package/dist/tests/cli/process.test.js.map +1 -1
  156. package/dist/tests/conformance/matrix.test.d.ts +6 -0
  157. package/dist/tests/conformance/matrix.test.js +23 -0
  158. package/dist/tests/conformance/matrix.test.js.map +1 -0
  159. package/dist/tests/conformance/test262/manifest.d.ts +115 -0
  160. package/dist/tests/conformance/test262/manifest.js +257 -0
  161. package/dist/tests/conformance/test262/manifest.js.map +1 -0
  162. package/dist/tests/conformance/test262.test.d.ts +11 -0
  163. package/dist/tests/conformance/test262.test.js +74 -0
  164. package/dist/tests/conformance/test262.test.js.map +1 -0
  165. package/dist/tests/docs/structure.test.js +9 -11
  166. package/dist/tests/docs/structure.test.js.map +1 -1
  167. package/dist/tests/e2e/child-process.test.js +3 -2
  168. package/dist/tests/e2e/child-process.test.js.map +1 -1
  169. package/dist/tests/e2e/compile-builtins.test.js +21 -0
  170. package/dist/tests/e2e/compile-builtins.test.js.map +1 -1
  171. package/dist/tests/e2e/compile-objects-classes.test.js +54 -0
  172. package/dist/tests/e2e/compile-objects-classes.test.js.map +1 -1
  173. package/dist/tests/e2e/differential-syntax.test.d.ts +5 -0
  174. package/dist/tests/e2e/differential-syntax.test.js +95 -0
  175. package/dist/tests/e2e/differential-syntax.test.js.map +1 -0
  176. package/dist/tests/e2e/differential-values.test.js +15 -0
  177. package/dist/tests/e2e/differential-values.test.js.map +1 -1
  178. package/dist/tests/e2e/gui-browser.test.d.ts +13 -0
  179. package/dist/tests/e2e/gui-browser.test.js +163 -0
  180. package/dist/tests/e2e/gui-browser.test.js.map +1 -0
  181. package/dist/tests/e2e/gui-example-browser.test.js +2 -2
  182. package/dist/tests/e2e/gui-example-browser.test.js.map +1 -1
  183. package/dist/tests/e2e/gui-example-canvas.test.js +8 -5
  184. package/dist/tests/e2e/gui-example-canvas.test.js.map +1 -1
  185. package/dist/tests/e2e/gui-example-svg.test.js +4 -3
  186. package/dist/tests/e2e/gui-example-svg.test.js.map +1 -1
  187. package/dist/tests/e2e/gui-example.test.js +4 -3
  188. package/dist/tests/e2e/gui-example.test.js.map +1 -1
  189. package/dist/tests/e2e/gui-helpers.d.ts +3 -0
  190. package/dist/tests/e2e/gui-helpers.js +6 -3
  191. package/dist/tests/e2e/gui-helpers.js.map +1 -1
  192. package/dist/tests/e2e/gui-media-disabled.test.d.ts +9 -0
  193. package/dist/tests/e2e/gui-media-disabled.test.js +42 -0
  194. package/dist/tests/e2e/gui-media-disabled.test.js.map +1 -0
  195. package/dist/tests/e2e/gui-media.test.d.ts +6 -4
  196. package/dist/tests/e2e/gui-media.test.js +20 -16
  197. package/dist/tests/e2e/gui-media.test.js.map +1 -1
  198. package/dist/tests/e2e/harness.d.ts +9 -0
  199. package/dist/tests/e2e/harness.js +14 -2
  200. package/dist/tests/e2e/harness.js.map +1 -1
  201. package/dist/tests/e2e/native-extensions.test.js +2 -1
  202. package/dist/tests/e2e/native-extensions.test.js.map +1 -1
  203. package/dist/tests/e2e/property-descriptors.test.js +20 -0
  204. package/dist/tests/e2e/property-descriptors.test.js.map +1 -1
  205. package/dist/tests/e2e/unicode-output.test.d.ts +16 -0
  206. package/dist/tests/e2e/unicode-output.test.js +67 -0
  207. package/dist/tests/e2e/unicode-output.test.js.map +1 -0
  208. package/dist/tests/e2e/weak-collections.test.js +16 -2
  209. package/dist/tests/e2e/weak-collections.test.js.map +1 -1
  210. package/dist/tests/extensions/media.test.d.ts +1 -0
  211. package/dist/tests/extensions/media.test.js +58 -0
  212. package/dist/tests/extensions/media.test.js.map +1 -0
  213. package/dist/tests/extensions/registry.test.js +8 -0
  214. package/dist/tests/extensions/registry.test.js.map +1 -1
  215. package/dist/tests/helpers.d.ts +1 -0
  216. package/dist/tests/helpers.js +1 -0
  217. package/dist/tests/helpers.js.map +1 -1
  218. package/dist/tests/lexer/identifiers.test.js +12 -0
  219. package/dist/tests/lexer/identifiers.test.js.map +1 -1
  220. package/dist/tests/lexer/scanner.test.js +8 -0
  221. package/dist/tests/lexer/scanner.test.js.map +1 -1
  222. package/dist/tests/lexer/strings.test.js +30 -0
  223. package/dist/tests/lexer/strings.test.js.map +1 -1
  224. package/dist/tests/parser/declarations.test.js +20 -0
  225. package/dist/tests/parser/declarations.test.js.map +1 -1
  226. package/dist/tests/parser/expressions.test.js +36 -0
  227. package/dist/tests/parser/expressions.test.js.map +1 -1
  228. package/dist/tests/platform.d.ts +32 -0
  229. package/dist/tests/platform.js +40 -0
  230. package/dist/tests/platform.js.map +1 -0
  231. package/dist/tests/platform.test.d.ts +12 -0
  232. package/dist/tests/platform.test.js +51 -0
  233. package/dist/tests/platform.test.js.map +1 -0
  234. package/dist/tests/version.test.js +4 -4
  235. package/dist/tests/version.test.js.map +1 -1
  236. package/doc/ai/README.md +10 -4
  237. package/doc/ai/build-recipe.md +1 -0
  238. package/doc/ai/cli.md +18 -6
  239. package/doc/ai/contributing.md +59 -2
  240. package/doc/ai/extensions.md +46 -23
  241. package/doc/ai/language-support.md +25 -16
  242. package/doc/ai/troubleshooting.md +9 -0
  243. package/doc/ai/zh-CN/README.md +9 -4
  244. package/doc/ai/zh-CN/build-recipe.md +1 -0
  245. package/doc/ai/zh-CN/cli.md +14 -4
  246. package/doc/ai/zh-CN/contributing.md +49 -3
  247. package/doc/ai/zh-CN/extensions.md +29 -8
  248. package/doc/ai/zh-CN/language-support.md +23 -14
  249. package/doc/ai/zh-CN/troubleshooting.md +8 -0
  250. package/doc/gui/api.md +45 -0
  251. package/doc/gui/build.md +37 -21
  252. package/doc/gui/known-issues.md +17 -6
  253. package/doc/gui/media.md +26 -11
  254. package/doc/gui/runtime.md +18 -0
  255. package/doc/gui-scripts.md +7 -0
  256. package/doc/gui.md +43 -33
  257. package/doc/implemented/binder.md +2 -0
  258. package/doc/implemented/checker.md +117 -0
  259. package/doc/implemented/cli.md +13 -1
  260. package/doc/implemented/codegen.md +3 -2
  261. package/doc/implemented/driver.md +2 -2
  262. package/doc/implemented/operators.md +2 -1
  263. package/doc/implemented/parser.md +3 -2
  264. package/doc/implemented/pipeline.md +8 -1
  265. package/doc/implemented/stdlib.md +2 -1
  266. package/doc/implemented/tests.md +3 -1
  267. package/doc/implemented.md +2 -0
  268. package/doc/npm-package.md +417 -0
  269. package/doc/requirements.md +4 -1
  270. package/doc/support-matrix.md +83 -0
  271. package/doc/unimplemented/classes.md +3 -0
  272. package/doc/unimplemented/deviations.md +3 -2
  273. package/doc/unimplemented/toolchain.md +1 -1
  274. package/doc/unimplemented/types.md +24 -8
  275. package/doc/unimplemented.md +1 -1
  276. package/doc/zh-CN/gui/api.md +41 -0
  277. package/doc/zh-CN/gui/build.md +28 -16
  278. package/doc/zh-CN/gui/known-issues.md +13 -5
  279. package/doc/zh-CN/gui/media.md +21 -10
  280. package/doc/zh-CN/gui/runtime.md +16 -0
  281. package/doc/zh-CN/gui-scripts.md +5 -0
  282. package/doc/zh-CN/gui.md +37 -32
  283. package/doc/zh-CN/implemented/binder.md +2 -0
  284. package/doc/zh-CN/implemented/checker.md +99 -0
  285. package/doc/zh-CN/implemented/cli.md +12 -1
  286. package/doc/zh-CN/implemented/codegen.md +3 -2
  287. package/doc/zh-CN/implemented/driver.md +2 -2
  288. package/doc/zh-CN/implemented/operators.md +1 -1
  289. package/doc/zh-CN/implemented/parser.md +3 -2
  290. package/doc/zh-CN/implemented/pipeline.md +3 -1
  291. package/doc/zh-CN/implemented/stdlib.md +2 -1
  292. package/doc/zh-CN/implemented/tests.md +3 -1
  293. package/doc/zh-CN/implemented.md +2 -0
  294. package/doc/zh-CN/npm-package.md +391 -0
  295. package/doc/zh-CN/post/announce.md +47 -47
  296. package/doc/zh-CN/requirements.md +4 -1
  297. package/doc/zh-CN/support-matrix.md +82 -0
  298. package/doc/zh-CN/unimplemented/classes.md +3 -0
  299. package/doc/zh-CN/unimplemented/deviations.md +3 -2
  300. package/doc/zh-CN/unimplemented/toolchain.md +1 -1
  301. package/doc/zh-CN/unimplemented/types.md +16 -6
  302. package/doc/zh-CN/unimplemented.md +1 -1
  303. package/llms.txt +4 -1
  304. package/package.json +3 -1
  305. package/runtime/ext_gui/audio.cpp +316 -0
  306. package/runtime/ext_gui/browser.cpp +547 -0
  307. package/runtime/ext_gui/browser_escape.cpp +85 -0
  308. package/runtime/ext_gui/browser_loop.cpp +83 -0
  309. package/runtime/ext_gui/canvas.cpp +9 -3
  310. package/runtime/ext_gui/canvas_raster.cpp +19 -1
  311. package/runtime/ext_gui/dom_api.cpp +36 -0
  312. package/runtime/ext_gui/dom_api_document.cpp +96 -5
  313. package/runtime/ext_gui/dom_api_events.cpp +20 -0
  314. package/runtime/ext_gui/dom_api_internal.h +19 -0
  315. package/runtime/ext_gui/dom_api_proto.cpp +6 -0
  316. package/runtime/ext_gui/gui.cpp +90 -23
  317. package/runtime/ext_gui/gui_engine.h +44 -0
  318. package/runtime/ext_gui/gui_media.cpp +69 -2
  319. package/runtime/ext_gui/media.cpp +34 -488
  320. package/runtime/ext_gui/media.h +54 -19
  321. package/runtime/ext_gui/media_api.h +65 -0
  322. package/runtime/ext_gui/window.cpp +9 -0
  323. package/runtime/ext_media/media.cpp +507 -0
  324. package/runtime/ext_media/media_bridge.c +35 -0
  325. package/runtime/ext_node/path/path.c +7 -7
  326. package/runtime/ext_node/url/url.c +4 -2
  327. package/runtime/rt.h +15 -0
  328. package/runtime/xt_constructors.c +2 -1
  329. package/runtime/xt_containers/objects.inc +22 -2
  330. package/runtime/xt_io/exception.inc +4 -2
  331. package/runtime/xt_stdlib/math.inc +62 -0
  332. package/runtime/xt_stdlib2/date.inc +7 -1
  333. package/runtime/xt_stdlib2/objects.inc +14 -0
  334. package/scripts/build-gui.ts +6 -72
  335. package/scripts/build-media.ts +245 -0
  336. package/scripts/support-matrix.ts +167 -0
  337. package/src/ast/common.ts +2 -0
  338. package/src/ast/declarations.ts +12 -1
  339. package/src/ast/expressions.ts +6 -0
  340. package/src/ast/kinds.ts +2 -0
  341. package/src/binder/binder.ts +3 -0
  342. package/src/binder/declarations.ts +70 -0
  343. package/src/binder/references.ts +84 -3
  344. package/src/binder/types.ts +30 -0
  345. package/src/canonical.ts +37 -0
  346. package/src/checker/assignability.ts +134 -0
  347. package/src/checker/calls.ts +135 -0
  348. package/src/checker/checker.ts +47 -0
  349. package/src/checker/declarations.ts +26 -0
  350. package/src/checker/flow.ts +236 -0
  351. package/src/checker/globals.ts +40 -0
  352. package/src/checker/source.ts +53 -0
  353. package/src/checker/type-infer.ts +185 -0
  354. package/src/checker/type-model.ts +212 -0
  355. package/src/checker/type-system.ts +578 -0
  356. package/src/checker/typecheck-types.ts +112 -0
  357. package/src/checker/typecheck.ts +586 -0
  358. package/src/checker/undefined.ts +43 -0
  359. package/src/checker/walk.ts +16 -0
  360. package/src/cli/help.ts +65 -0
  361. package/src/cli/hints.ts +13 -1
  362. package/src/cli/main.ts +12 -49
  363. package/src/codegen/generator/calls/access.ts +8 -8
  364. package/src/codegen/generator/calls/invocation.ts +8 -5
  365. package/src/codegen/generator/calls/super.ts +67 -5
  366. package/src/codegen/generator/context.ts +31 -19
  367. package/src/codegen/generator/debug.ts +2 -1
  368. package/src/codegen/generator/expressions/primary.ts +84 -13
  369. package/src/codegen/generator/generator.ts +11 -1
  370. package/src/codegen/generator/module.ts +65 -24
  371. package/src/codegen/generator/state.ts +11 -1
  372. package/src/codegen/generator/statements/variables.ts +20 -3
  373. package/src/codegen/generator/tables.ts +5 -0
  374. package/src/driver/build-key.ts +3 -0
  375. package/src/driver/bundler/graph.ts +6 -2
  376. package/src/driver/bundler/merge.ts +14 -1
  377. package/src/driver/bundler/types.ts +13 -0
  378. package/src/driver/compiler.ts +5 -1
  379. package/src/driver/fingerprint.ts +2 -1
  380. package/src/driver/frontend.ts +13 -2
  381. package/src/driver/options.ts +6 -0
  382. package/src/driver/version.ts +1 -1
  383. package/src/extensions/catalog.ts +2 -1
  384. package/src/extensions/gui/html.ts +23 -10
  385. package/src/extensions/gui/index.ts +65 -0
  386. package/src/extensions/media/index.ts +67 -0
  387. package/src/extensions/registry.ts +72 -0
  388. package/src/index.ts +2 -0
  389. package/src/parser/declarations/classes.ts +7 -0
  390. package/src/parser/expressions.ts +13 -1
  391. package/src/parser/literals.ts +6 -2
package/doc/gui/build.md CHANGED
@@ -4,21 +4,27 @@
4
4
  > decisions and roadmap live there.
5
5
 
6
6
  - Sources live in `runtime/ext_gui/` (C/C++) plus vendored libs under `vendor/`
7
- (gitignored; fetched on demand).
7
+ (gitignored; fetched on demand). Media decoding lives in
8
+ `runtime/ext_media/` and is built separately.
8
9
  - `npm run gui` (`scripts/build-gui.ts`) fetches a pinned SDL3 (`SDL3_TAG`,
9
10
  default `release-3.2.10`), builds a static SDL3, fetches and builds static
10
11
  FreeType (`FREETYPE_VERSION`) and HarfBuzz (`HARFBUZZ_VERSION`), compiles the
11
12
  engine and merges everything into `runtime/lib/<os>-<arch>/gui.a` (or
12
13
  `gui.lib` with the MSVC ABI on Windows), same convention as `core.a`,
13
- statically bundling all three. It also fetches, configures and builds a
14
- minimal static **FFmpeg** (`FFMPEG_VERSION`, default `7.1`) with only the
15
- demuxers/parsers/decoders the media elements need and merges those archives
16
- into `gui.a`, defining `XT_GUI_WITH_FFMPEG` for the engine. The merge uses
17
- `libtool` on macOS and `ar -M` (GNU/LLVM) elsewhere; CMake archives are
18
- discovered under the build root or `Release/` for either generator style.
19
- - `src/extensions/gui/index.ts` exposes the archive through `nativeObjects()`
20
- (via `findRuntimeLibrary`, so `.a`/`.lib` both work) and the OS frameworks
21
- through `linkerFlags()`.
14
+ statically bundling all three. The merge uses `libtool` on macOS and
15
+ `ar -M` (GNU/LLVM) elsewhere; CMake archives are discovered under the build
16
+ root or `Release/` for either generator style.
17
+ - `npm run media` (`scripts/build-media.ts`) builds the optional **FFmpeg**
18
+ backend. It fetches FFmpeg (`FFMPEG_VERSION`, default `7.1`), configures a
19
+ minimal static build with only the demuxers/parsers/decoders the media
20
+ elements need, compiles `runtime/ext_media/media.cpp` against it and merges
21
+ everything into `runtime/lib/<os>-<arch>/media.a`. `gui.a` does **not** link
22
+ FFmpeg: a program enables playback explicitly with `--ext media`.
23
+ - `src/extensions/gui/index.ts` exposes the engine archive through
24
+ `nativeObjects()` (via `findRuntimeLibrary`, so `.a`/`.lib` both work) and the
25
+ OS frameworks through `linkerFlags()`. `src/extensions/media/index.ts` does
26
+ the same for `media.a` and compiles the registration bridge
27
+ (`runtime/ext_media/media_bridge.c`) as a normal runtime source.
22
28
  - `scripts/build-gui.ts` compiles with the *same* clang the driver resolves
23
29
  (`src/driver/toolchain-provider.ts`); on Windows that is the MSVC-targeting
24
30
  LLVM bundled with Visual Studio, and its sibling `clang++`/`llvm-ar` are used
@@ -26,14 +32,17 @@
26
32
  fallbacks, and Windows always uses `llvm-ar`, so the archive cannot mix object
27
33
  formats or C++ runtimes. The Visual Studio toolchain is found by absolute
28
34
  path, so no developer prompt is required. On Windows SDL_GPU selects the
29
- Vulkan backend; no DXIL/`dxc` toolchain is needed.
30
- - CI builds `gui.a` before assembling the release archive so it ships inside
31
- `runtime/lib/<slug>/` (the release tarball copies the whole `runtime/` tree).
32
- The archive is built and the example is run on Linux (under Xvfb, with the
33
- lavapipe software Vulkan driver) and macOS; Windows is provisional because the
34
- hosted runners have no GPU/Vulkan driver.
35
- - The existing cache fingerprint already hashes `nativeObjects()` contents, so
36
- rebuilding `gui.a` invalidates cached binaries automatically.
35
+ Vulkan backend; no DXIL/`dxc` toolchain is needed. `scripts/build-media.ts`
36
+ uses the same resolved toolchain for FFmpeg and the player.
37
+ - CI builds `gui.a` and `media.a` before assembling the release archive so they
38
+ ship inside `runtime/lib/<slug>/` (the release tarball copies the whole
39
+ `runtime/` tree). The archives are built and the examples are run on Linux
40
+ (under Xvfb, with the lavapipe software Vulkan driver) and macOS; Windows is
41
+ provisional because the hosted runners have no GPU/Vulkan driver, and the
42
+ media archive is POSIX-only.
43
+ - The existing cache fingerprint already hashes `nativeObjects()` contents and
44
+ `runtimeSources()` content, so rebuilding either archive invalidates cached
45
+ binaries automatically.
37
46
  - CMake build trees live *next to* their sources (`vendor/sdl-build`,
38
47
  `vendor/freetype-build`, `vendor/harfbuzz-build`), never inside them: a
39
48
  `CMakeCache.txt` records the machine it was configured on, and SDL's video
@@ -52,6 +61,7 @@
52
61
  ```sh
53
62
  npm run runtime # rebuild core.a after a runtime change
54
63
  npm run gui # build runtime/lib/<os>-<arch>/gui.a (fetches SDL3 once)
64
+ npm run media # optional: build media.a (fetches and builds FFmpeg once)
55
65
  xbintsc run examples/gui/hello.ts --ext gui
56
66
  ```
57
67
 
@@ -62,9 +72,10 @@ its README for controls and the geometry report it prints.
62
72
 
63
73
  `media.ts` (with `media.html`) demonstrates `<video>`/`<audio>`: it overlays a
64
74
  CSS progress bar on the video and drives playback with `play()` / `pause()` /
65
- `currentTime` / `volume`. Media `src` paths resolve relative to the process
66
- working directory, so run it from the repository root:
67
- `xbintsc run examples/gui/media.ts --ext gui`.
75
+ `currentTime` / `volume`. It needs the separate `media` extension, so build and
76
+ enable both. Media `src` paths resolve relative to the process working
77
+ directory, so run it from the repository root:
78
+ `xbintsc run examples/gui/media.ts --ext gui,media`.
68
79
 
69
80
  Set `XT_GUI_AUTOCLOSE_MS=<n>` to close all windows after `n` milliseconds,
70
81
  which the e2e test (`tests/e2e/gui-*.test.ts`) uses to run headlessly.
@@ -84,10 +95,15 @@ software Vulkan driver:
84
95
  ```sh
85
96
  sudo sh scripts/install-gui-deps.sh # clang, cmake, X11/Wayland headers, Vulkan, Xvfb
86
97
  npm run runtime && npm run gui
98
+ npm run media # optional: <video>/<audio> playback
87
99
  xvfb-run -a --server-args="-screen 0 1280x720x24" \
88
100
  npx tsx src/cli/main.ts run examples/gui/hello.ts --ext gui
89
101
  ```
90
102
 
103
+ The media e2e suite (`tests/e2e/gui-media.test.ts`) skips itself unless both
104
+ `gui.a` and `media.a` exist; `tests/e2e/gui-media-disabled.test.ts` covers the
105
+ GUI-only build and runs with `gui.a` alone.
106
+
91
107
  `scripts/install-gui-deps.sh` holds the package list (`apt-get install -y clang
92
108
  cmake libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev
93
109
  libxinerama-dev libxfixes-dev libxkbcommon-dev libwayland-dev wayland-protocols
@@ -5,6 +5,16 @@
5
5
 
6
6
  ## Known issues
7
7
 
8
+ - **No WebGL.** `getContext("webgl")` / `getContext("webgl2")` answer `null` and
9
+ the `WebGL*` / `WebGL2RenderingContext` / `XRWebGL*` globals are `undefined`,
10
+ so a WebGL page such as a Three.js scene fails with the library's own
11
+ "Error creating WebGL context" and is expected to show its fallback panel.
12
+ Only `getContext("2d")` is backed by a rasteriser (see
13
+ [Canvas](./canvas.md)). Everything else about a ported page — module graph,
14
+ DOM handles, events, the browser globals in [API](./api.md#browser-globals),
15
+ the frame pump — works, so a Three.js program *compiles and starts*; it just
16
+ cannot draw.
17
+
8
18
  - **Intermittent crash at auto-close.** `XT_GUI_AUTOCLOSE_MS` can end a run
9
19
  with a native access violation in roughly two runs out of five; a clean exit
10
20
  looks identical otherwise. Windows reports it as the NTSTATUS exit code
@@ -69,12 +79,13 @@
69
79
  (`win.driver()` reports `"vulkan"`), so the archive needs no DXIL/`dxc`
70
80
  toolchain; the hosted Windows runners have no GPU/Vulkan driver, which is why
71
81
  the CI run stays provisional.
72
- - **Media on Windows:** the media decoders (FFmpeg) are only built and merged
73
- into the POSIX `gui.a`; the Windows `gui.lib` is produced without them, so
74
- `<video>`/`<audio>` are inert there (failures fire `error`). Enabling it needs
75
- an MSVC-compatible FFmpeg build and is deferred until the Windows GUI path
76
- itself is validated. `<video controls>` is likewise deferred — the intended
77
- pattern is TS + a CSS overlay, as in `examples/gui/media.ts`.
82
+ - **Media on Windows:** the `media` extension is POSIX-only for now. The GUI
83
+ engine itself builds on Windows, but without the extension `<video>`/`<audio>`
84
+ are inert there (an open fails and fires `error`), and `--ext media` reports an
85
+ actionable error instead of linking. Enabling it needs an MSVC-compatible
86
+ FFmpeg build and is deferred until the Windows GUI path itself is validated.
87
+ `<video controls>` is likewise deferred — the intended pattern is TS + a CSS
88
+ overlay, as in `examples/gui/media.ts`.
78
89
  - **D3D12 shaders:** the SPIR-V (Vulkan) and DXIL (Direct3D 12) blobs are built
79
90
  and embedded, so the non-Metal path no longer skips geometry. DXIL remains
80
91
  unusable on **SDL 3.2.10**: its D3D12 backend rejects any graphics pipeline
package/doc/gui/media.md CHANGED
@@ -65,17 +65,31 @@ clip paths are not rendered (see [Known issues](./known-issues.md)).
65
65
 
66
66
  ## Video & audio (M13)
67
67
 
68
- `runtime/ext_gui/media.{h,cpp}` wraps a statically vendored **FFmpeg** build and
69
- `runtime/ext_gui/gui_media.cpp` connects the DOM tree to it. `<video>` and
70
- `<audio>` really decode and play; there is no WebView and no platform media
71
- framework in the path.
68
+ Media playback is split across two extensions so a GUI program does not pay for
69
+ a decoder it never uses:
70
+
71
+ - **`gui`** (`gui.a`) owns the `<video>`/`<audio>` elements, the DOM API, the
72
+ renderer integration and the SDL audio sink, but contains **no FFmpeg**.
73
+ `runtime/ext_gui/media.{h,cpp}` declares the player interface and dispatches
74
+ through a table the media backend installs at startup
75
+ (`runtime/ext_gui/media_api.h`).
76
+ - **`media`** (`media.a`, `runtime/ext_media/`) is the optional decoder
77
+ backend: `runtime/ext_media/media.cpp` wraps a statically vendored **FFmpeg**
78
+ build, and `runtime/ext_media/media_bridge.c` registers it with the engine.
79
+ Enable it with `--ext media` (or `--ext gui,media`). `media` requires `gui`;
80
+ the registry rejects the combination in the wrong order.
81
+
82
+ Without the `media` extension the element still exists and its DOM API is
83
+ callable, but opening a source fails and fires `error`. That is also how Windows
84
+ behaves today: the archive is POSIX-only. There is no WebView and no platform
85
+ media framework in the path either way.
72
86
 
73
87
  - **Decoding.** `avformat_open_input` opens the `src` (a path — `file://` is
74
88
  accepted, but media paths are *not* percent-decoded, unlike images), the
75
89
  best stream is selected for each kind, and a software decoder yields
76
90
  `yuv/rgb` frames which `sws_scale` converts to RGBA8 at the coded size. The
77
91
  supported containers/codecs are the minimal FFmpeg configuration from
78
- `scripts/build-gui.ts`: MP4/MOV/MKV/AVI/FLV/MPEG-TS/M4V/ASF, MP3/OGG/WAV/FLAC/
92
+ `scripts/build-media.ts`: MP4/MOV/MKV/AVI/FLV/MPEG-TS/M4V/ASF, MP3/OGG/WAV/FLAC/
79
93
  AAC; H.264, HEVC, VP8, VP9, AV1, MPEG-4, MJPEG video; AAC, MP3, Opus, Vorbis,
80
94
  FLAC, ALAC, AC3/E-AC3, WMAv2 and the raw PCM formats audio.
81
95
  - **Video.** `<video>` is a replaced element like `<img>` (UA default
@@ -83,13 +97,14 @@ framework in the path.
83
97
  same `PaintImage` as an image; the renderer uploads each new decoded frame to
84
98
  an RGBA texture (`ensureMediaTexture`) and draws a textured quad, so the GPU
85
99
  scales it to the CSS box instead of the CPU resizing. Playback timing is the
86
- wall clock (`SDL_GetTicks`), not the frame delta.
100
+ process monotonic clock, not the frame delta.
87
101
  - **Audio.** There is no audio callback: the decoder is pushed on the main
88
- thread as it is ticked and the PCM is queued with
89
- `SDL_OpenAudioDeviceStream` in push mode (`NULL` callback), buffering about
90
- 0.25 s ahead at 48 kHz stereo `SDL_AUDIO_F32`. `volume` maps to
91
- `SDL_SetAudioStreamGain`; audio is best-effort and is skipped when no device
92
- is available (headless CI).
102
+ thread as it is ticked and writes into an `xtgui::AudioSink`. The GUI
103
+ implements that sink in `gui_media.cpp` with `SDL_OpenAudioDeviceStream` in
104
+ push mode (`NULL` callback), buffering about 0.25 s ahead at 48 kHz stereo
105
+ `SDL_AUDIO_F32`. `volume` maps to `SDL_SetAudioStreamGain`; audio is
106
+ best-effort and is skipped when no device is available (headless CI). Keeping
107
+ the sink in `gui.a` means `media.a` depends only on FFmpeg.
93
108
  - **Threading.** The engine is single-threaded and not thread-aware, so all
94
109
  decoding happens on the main thread inside `xt_gui_media_tick` — no decode
95
110
  thread, no cross-thread GC exposure.
@@ -27,6 +27,24 @@ plain native call the TypeScript program controls. Each tick it:
27
27
  The `xt_loop_set_main` hook remains available for hosts that want to own the
28
28
  loop themselves.
29
29
 
30
+ ### The frame pump (pages that never call `run()`)
31
+
32
+ A page written for the browser does not call `run()`; it calls
33
+ `requestAnimationFrame` and expects the host to paint. `browser_loop.cpp` covers
34
+ that case with a single 16 ms `xt_set_timeout` tick:
35
+
36
+ - it starts at `loadHTML`, not at the first `requestAnimationFrame` — `ready` is
37
+ emitted by the first *presented* frame, so waiting for the page's callback
38
+ would deadlock;
39
+ - each tick dispatches pending input, renders every open window (which drains
40
+ queued animation-frame callbacks before layout, so a page can stop itself),
41
+ - it re-arms **only while callbacks remain**, so an idle page lets the event
42
+ loop drain and the process exit — the browser-tab lifecycle;
43
+ - it stands aside while `xt_gui_run_active()` is set (the program called
44
+ `run()`), so the same window is not rendered twice per tick;
45
+ - `XT_GUI_AUTOCLOSE_MS=n` makes the pump quit after `n` milliseconds, which is
46
+ how the tests run a page that never closes itself.
47
+
30
48
  This keeps network I/O, timers and `await` working inside a GUI program.
31
49
 
32
50
  ## Native ↔ TS bridge
@@ -170,6 +170,13 @@ Two limitations are enforced with clear errors rather than silent breakage:
170
170
  `src` URLs (`https://…`, `data:…`, `//host`) are left untouched — they are not
171
171
  compile-time assets and never run.
172
172
 
173
+ A wrapped body keeps its own file as the origin of every statement in it (the
174
+ loader reports the body's span in the generated module as a *source range*), so
175
+ a diagnostic points at `app.js:12` rather than at a column of `index.html`, and
176
+ a **plain-JavaScript** script stays untyped exactly like a `.js` module imported
177
+ directly: `state.update = …` on an object literal is not a `TS4003`. A page can
178
+ therefore ship its existing scripts unchanged.
179
+
173
180
  ```html
174
181
  <button id="b">0</button>
175
182
  <script src="./counter.ts"></script>
package/doc/gui.md CHANGED
@@ -21,9 +21,11 @@ what `examples/gui/pelican-bike` — a playable 2D game — is built on. **M12**
21
21
  DOM node lifetime explicit (what a mutation releases, what it keeps) and gives the
22
22
  engine bounded memory: see [Node lifetime](./gui/dom.md#node-lifetime) and
23
23
  [Memory & GC](./gui/runtime.md#memory--gc). **M13** plays real
24
- `<video>`/`<audio>` — a vendored minimal FFmpeg decodes them on the main thread,
25
- video frames go through the image texture path and audio to an SDL stream, with
26
- the DOM media API exposing `play`/`pause`/`currentTime`/… and media events.
24
+ `<video>`/`<audio>` — the optional `media` extension decodes them on the main
25
+ thread with a vendored minimal FFmpeg, video frames go through the image texture
26
+ path and audio to an SDL stream, with the DOM media API exposing
27
+ `play`/`pause`/`currentTime`/… and media events. Enabling `gui` alone does not
28
+ link FFmpeg.
27
29
  **M14** adds `<canvas>` with a self-written 2D software rasteriser (anti-aliased
28
30
  fills, paths, text and `drawImage`) uploaded through the image texture path —
29
31
  see [Canvas](./gui/canvas.md). **M15** adds CSS `transform` /
@@ -84,7 +86,7 @@ pages above.
84
86
  | 4 | The engine is **not self-hosted** (it is C/C++, not TS), but must not affect the compiler's platform-agnostic design. Delivered as a per-platform prebuilt archive linked via `nativeObjects`. |
85
87
  | 5 | The **event loop is generic**: the runtime exposes a generic main-loop hook and a poll primitive; nothing GUI-specific enters `runtime/`. |
86
88
  | 6 | **Multiple windows** are supported by the core object model. |
87
- | 7 | Third-party low-level libs are **statically linked into `gui.a`** so releases stay self-contained; only OS frameworks are added at link time. |
89
+ | 7 | Third-party low-level libs are **statically linked into the extension archives** so releases stay self-contained; only OS frameworks are added at link time. `gui.a` carries SDL3/FreeType/HarfBuzz, and the optional `media.a` carries FFmpeg and is linked only with `--ext media`. |
88
90
 
89
91
  ## Architecture
90
92
 
@@ -106,6 +108,7 @@ pages above.
106
108
  windowing + input (SDL3) ── multiple windows
107
109
  text (HarfBuzz + FreeType) ── glyph atlas / SDF
108
110
  images (stb_image; SVG via NanoSVG)
111
+ media DOM + audio sink ── optional media.a (FFmpeg) installs the decoder
109
112
  ```
110
113
 
111
114
  The engine never talks to the compiler. The compiler only sees an `Extension`
@@ -120,18 +123,18 @@ with `nativeObjects()`, `linkerFlags()` and `modules()`.
120
123
  | Text shaping | **HarfBuzz** | correct complex-script shaping |
121
124
  | Glyph raster | **FreeType** | glyph outlines → GPU atlas / SDF |
122
125
  | Images | **stb_image** (vendored header) for bitmaps, **NanoSVG** (vendored headers) for SVG | single headers to start; SVG files rasterise on demand |
123
- | Video + audio | **FFmpeg** (statically vendored, minimal build) | decodes the common container/codec set; no WebView or platform media framework |
126
+ | Video + audio | **FFmpeg** (statically vendored, minimal build, optional `media` extension) | decodes the common container/codec set; no WebView or platform media framework |
124
127
 
125
128
  Pinned versions: SDL3 `release-3.2.10`, FreeType `2.13.3`, HarfBuzz `10.1.0`,
126
- FFmpeg `7.1` (overridable with `SDL3_TAG` / `FREETYPE_VERSION` /
127
- `HARFBUZZ_VERSION` / `FFMPEG_VERSION`).
129
+ FFmpeg `7.1` for the optional `media` archive (overridable with `SDL3_TAG` /
130
+ `FREETYPE_VERSION` / `HARFBUZZ_VERSION` / `FFMPEG_VERSION`).
128
131
 
129
132
  Alternative if SDL3 is rejected: **GLFW + OpenGL 3.3** (simpler, but OpenGL is
130
133
  deprecated on macOS and gives no modern GPU abstraction). **wgpu-native** if the
131
134
  engine were Rust.
132
135
 
133
- > These vendored libraries are linked **statically into `gui.a`** so a released
134
- > xbintsc stays "download and run"; only OS frameworks are added by
136
+ > These vendored libraries are linked **statically into `gui.a` / `media.a`** so
137
+ > a released xbintsc stays "download and run"; only OS frameworks are added by
135
138
  > `linkerFlags()`.
136
139
 
137
140
  ## Milestones
@@ -172,15 +175,16 @@ engine were Rust.
172
175
  animated `background-color`/`color`/`border-color`/`border-radius`, retargeting
173
176
  and `win.advance(ms)`. `@keyframes` remain.
174
177
  7. **M7 — CI & releases** ✅ (Linux/macOS build) / 🚧 (run + Windows)
175
- - `compile-examples` builds `gui.a` on Linux and macOS (required), then runs
176
- the example and `tests/e2e/gui-*.test.ts` under Xvfb + lavapipe on Linux
177
- (required). The macOS run is provisional until a WindowServer is confirmed;
178
- it is guarded so a failure is logged without annotating the run.
179
- - The `package` job builds `gui.a` before assembling the release, so it ships
180
- inside the existing runtime archive (`package-release` copies all of
181
- `runtime/`).
182
- - `vendor/` (SDL3/FreeType/HarfBuzz, the slow part) is cached per OS/arch,
183
- keyed by `scripts/build-gui.ts`.
178
+ - `compile-examples` builds `gui.a` and `media.a` on Linux and macOS
179
+ (required), then runs the examples and `tests/e2e/gui-*.test.ts` under
180
+ Xvfb + lavapipe on Linux (required). The macOS run is provisional until a
181
+ WindowServer is confirmed; it is guarded so a failure is logged without
182
+ annotating the run.
183
+ - The `package` job builds `gui.a` and `media.a` before assembling the
184
+ release, so both ship inside the existing runtime archive
185
+ (`package-release` copies all of `runtime/`).
186
+ - `vendor/` (SDL3/FreeType/HarfBuzz for `gui.a`, FFmpeg for `media.a`) is
187
+ cached per OS/arch, keyed by `scripts/build-gui.ts` / `scripts/build-media.ts`.
184
188
  - Windows (build + run) stays provisional in CI: the MSVC-compatible
185
189
  `gui.lib` builds and runs locally through SDL_GPU's Vulkan backend, but the
186
190
  hosted runners have no GPU/Vulkan driver. A failure is logged without
@@ -234,13 +238,15 @@ engine were Rust.
234
238
  `tests/e2e/gui-retention.test.ts` (see [Memory & GC](./gui/runtime.md#memory--gc)).
235
239
  13. **M13 — video & audio** ✅
236
240
  - `<video>` / `<audio>` decode through a statically vendored minimal FFmpeg
237
- (`media.*`, `gui_media.cpp`), frames upload to GPU textures through the
238
- existing image pipeline, audio is pushed to an SDL stream on the main
239
- thread, and the DOM media API plus `loadedmetadata`/`play`/`pause`/
240
- `ended`/`timeupdate`/`error` events are exposed on element handles
241
+ in the optional `media` extension (`runtime/ext_media/media.cpp`), frames
242
+ upload to GPU textures through the existing image pipeline, audio is
243
+ pushed to an SDL stream on the main thread by the GUI's audio sink, and
244
+ the DOM media API plus `loadedmetadata`/`play`/`pause`/`ended`/
245
+ `timeupdate`/`error` events are exposed on element handles
241
246
  (`dom_api_media.cpp`, `dom_api_proto.cpp`). Controlled from TS + CSS;
242
247
  there are no built-in controls. Example in `examples/gui/media.*`, e2e in
243
- `tests/e2e/gui-media.test.ts`.
248
+ `tests/e2e/gui-media.test.ts` (with the `media` extension) and
249
+ `tests/e2e/gui-media-disabled.test.ts` (without it).
244
250
  14. **M14 — `<canvas>` 2D** ✅
245
251
  - `<canvas>` is a replaced element (`xtgui::Canvas2D`, `layout.*`), the
246
252
  `getContext("2d")` handle and drawing API live in `dom_api_canvas.cpp`,
@@ -300,10 +306,11 @@ engine were Rust.
300
306
  pixel size and cached by that size, so scaling and HiDPI stay crisp.
301
307
  - **M6b** ✅ CSS transitions (parsing in `style.*`, an animation clock and
302
308
  transition state in `document.*`, `advance`/`advance(ms)` hooks, e2e coverage).
303
- - **M7** ✅ builds `gui.a` in CI on Linux and macOS (required) and runs the
304
- example plus the GUI e2e suite under Xvfb on Linux; `package` ships `gui.a`,
305
- `vendor/` is cached, and the `ar -M` merge works on GNU/Linux and macOS.
306
- macOS runs and all of Windows remain provisional in CI.
309
+ - **M7** ✅ builds `gui.a` (and the optional `media.a`) in CI on Linux and macOS
310
+ (required) and runs the example plus the GUI e2e suite under Xvfb on Linux;
311
+ `package` ships both archives, `vendor/` is cached, and the `ar -M` merge
312
+ works on GNU/Linux and macOS. macOS runs and all of Windows remain provisional
313
+ in CI.
307
314
  - **M8** ✅ element/document handles (`dom_api.*`), DOM mutation with lazy
308
315
  restyle/relayout (`document.*`, `xt_gui_flush_dom`), element event dispatch
309
316
  with capture/bubble and `stopPropagation` (`dom_api.*`, `gui.cpp`), and e2e
@@ -338,14 +345,17 @@ engine were Rust.
338
345
  ratcheting upwards. `win.stats()` exposes the engine counters and
339
346
  `tests/e2e/gui-retention.test.ts` pins them; a game loop rewriting its sprite
340
347
  every frame now runs in constant memory (see [Memory & GC](./gui/runtime.md#memory--gc)).
341
- - **M13** ✅ `<video>` / `<audio>` support. A minimal static FFmpeg is vendored
342
- and merged into `gui.a` (`scripts/build-gui.ts`), `media.*` decodes video to
343
- RGBA frames and audio to 48 kHz stereo PCM on the main thread, `gui_media.cpp`
344
- owns the players and pumps the media clock and events each frame,
348
+ - **M13** ✅ `<video>` / `<audio>` support. The optional `media` extension
349
+ vendors and builds a minimal static FFmpeg (`scripts/build-media.ts`) and
350
+ merges it into `media.a`; `runtime/ext_media/media.cpp` decodes video to RGBA
351
+ frames and audio to 48 kHz stereo PCM on the main thread,
352
+ `runtime/ext_gui/gui_media.cpp` owns the players, implements the SDL audio
353
+ sink and pumps the media clock and events each frame,
345
354
  `renderer_image.cpp` uploads each new video frame through the image texture
346
355
  path, and `dom_api_media.cpp` exposes `play`/`pause`/`load` plus the media
347
- properties on element handles. `examples/gui/media.*` demonstrates the
348
- TS-plus-CSS-controls pattern and `tests/e2e/gui-media.test.ts` pins it.
356
+ properties on element handles. `gui.a` stays FFmpeg-free; enabling `media`
357
+ without `gui` is rejected by the registry. `examples/gui/media.*` demonstrates
358
+ the TS-plus-CSS-controls pattern and `tests/e2e/gui-media.test.ts` pins it.
349
359
  - **M14** ✅ `<canvas>` support. A new replaced element (`layout.*`) carries an
350
360
  intrinsic size from its `width`/`height` attributes (default `300x150`),
351
361
  `xtgui::Canvas2D` (`canvas.{h,cpp}`) owns the RGBA8 bitmap and drawing state,
@@ -7,6 +7,8 @@ Location: `src/binder/binder.ts`
7
7
  - Scope kinds: module, function, block, `for`, `catch`
8
8
  - Symbol kinds: `var` / `let` / `const` / `function` / `parameter` / `class` / `interface` / `type` / `enum` / `import` / `namespace`
9
9
  - `var` and function declarations hoist to the function scope; `let` / `const` stay block-scoped
10
+ - A `switch` body is one shared block scope: the declarations of every `case` / `default` clause are pre-declared before any clause is bound
11
+ - A `static { ... }` class block is bound as a hidden static function of the class (see [Classes](../unimplemented/classes.md))
10
12
  - Identifier → declaration resolution; unresolved identifier collection (`CannotFindName`)
11
13
  - Closure capture analysis: outer variables referenced by an inner function are marked `captured` / `boxed`, and capture indices are threaded through intermediate closures
12
14
  - Parameters are registered as local symbols; the self-name of a named function expression is registered as `const`
@@ -0,0 +1,117 @@
1
+ # Semantic checker
2
+
3
+ > Part of [Implemented syntax and features](../implemented.md) · [简体中文](../zh-CN/implemented/checker.md)
4
+
5
+ Location: `src/checker/` (`checker.ts`, `undefined.ts`, `declarations.ts`,
6
+ `calls.ts`, `type-system.ts`, `assignability.ts`, `flow.ts`, `typecheck.ts`),
7
+ invoked by `generate()` between binding and LLVM lowering.
8
+
9
+ The checker runs **by default**; `--no-check` (or `check: false` in the
10
+ programmatic API) turns it off. It combines inference-free checks with a small
11
+ structural type model:
12
+
13
+ | Diagnostic | Code | What is checked |
14
+ | --- | --- | --- |
15
+ | `Cannot find name` | TS3002 | An identifier that resolves to no declaration and no runtime global |
16
+ | `Duplicate identifier` | TS3001 | Same-scope declarations that cannot merge (`let x` twice, `function f` then `const f`, `let` colliding with a parameter, ...) |
17
+ | `Argument count mismatch` | TS4004 | A direct call to a locally visible function or `const`-bound arrow/function expression with too few or too many arguments |
18
+ | `Property not found` | TS4003 | A property read on a shape that is statically known |
19
+ | `Type mismatch` | TS4001 | An initializer, assignment, return value or call argument that is definitely not assignable |
20
+ | `Not callable` | TS4002 | Calling a value whose type is a primitive (number, string, boolean, ...) |
21
+
22
+ ## What the type model knows
23
+
24
+ The checker resolves the type syntax it can understand and treats everything
25
+ else as `any`:
26
+
27
+ - keyword types, literal types, `A | B` unions and object type literals;
28
+ - interfaces and type aliases (including generic aliases and `extends`);
29
+ - classes: instance fields, methods, accessors, parameter properties,
30
+ `this.x = ...` members and local ancestor classes. Static members are not
31
+ instance members;
32
+ - arrays, tuples, function types, object literals and `new LocalClass()`;
33
+ - simple generics: a type parameter is `any` at its declaration, and a call
34
+ infers it from an argument (`T`, `T[]`, `Array<T>`) or takes it from an
35
+ explicit type argument list.
36
+
37
+ Anything the model cannot name — mapped/conditional types, `keyof`,
38
+ `typeof` queries, indexed access, utility types, imported type names that
39
+ bundling renamed, an unknown base class — becomes `any`. `any` is compatible
40
+ with everything, which is the central safety property: unsupported syntax can
41
+ hide a bug, but it cannot reject working code.
42
+
43
+ ## Assignability
44
+
45
+ Checked at variable initializers, `=` assignments, `return` statements and call
46
+ arguments:
47
+
48
+ - primitives and literal types;
49
+ - object/interface/class shapes: every required target property must exist and
50
+ be assignable; extra source properties are allowed;
51
+ - arrays and tuples element-wise;
52
+ - functions: parameter count and return type (conservatively);
53
+ - unions: every source member must fit a target member, or some target member
54
+ must accept the source.
55
+
56
+ `let`/`var` infer widened types (`let x = 1` is `number`), `const` keeps the
57
+ literal. `null` and `undefined` are accepted wherever a value is expected
58
+ (there is no strict-null mode). Functional return types are not inferred: an
59
+ unannotated function returns `any`, so its callers are never rejected.
60
+
61
+ ## Property existence
62
+
63
+ Shapes come from an explicit annotation or from a `const` initialized with an
64
+ object literal / `new LocalClass(...)`. Optional properties, `Object.prototype`
65
+ members (`toString`, `hasOwnProperty`, ...), index signatures and inherited
66
+ class members are all accepted.
67
+
68
+ A shape becomes untrusted — and its variable is left alone — when it can change
69
+ after the declaration: a property write/delete/update, a call that may mutate
70
+ it (`mutate(object)`, `Object.assign(object, ...)`), aliasing (`const p =
71
+ object`), a dynamic constructor (`Object.assign(this, ...)`, `this[key] = ...`)
72
+ or prototype augmentation (`Object.assign(C.prototype, ...)`). Writes to a
73
+ missing property are allowed (xbintsc programs legitimately grow objects after
74
+ their literal); the write opens the shape instead of reporting.
75
+
76
+ Not checked: `object["x"]` element access, destructuring, shapes reached
77
+ through a function return, or aliasing through array/object containers.
78
+
79
+ ## Narrowing
80
+
81
+ Inside a branch the checker refines a variable when the condition is one of:
82
+
83
+ - `value !== null` / `!== undefined` / `!= null` (and the `===` forms);
84
+ - `typeof value === "string" | "number" | "boolean" | "bigint" | "symbol" | "undefined"`;
85
+ - `value instanceof LocalClass`;
86
+ - truthiness (`if (value)`, `value &&`, `value ||`);
87
+ - combinations through `&&`, `||`, `??` and `!`.
88
+
89
+ `if`/`else` and conditional expressions (`cond ? a : b`) apply the refinement;
90
+ other control flow does not.
91
+
92
+ ## What is deliberately not checked
93
+
94
+ - Full inference: unannotated function returns, complex generic constraints and
95
+ higher-order inference are treated as `any`.
96
+ - Excess-property checks on fresh object literals.
97
+ - `as`/`satisfies` assertions may narrow or widen freely (they are erased).
98
+ - Overload resolution, mapped types, conditional types and template-literal
99
+ types are not modeled.
100
+ - Bundled sources under `node_modules` are not checked at all: the checker is a
101
+ gate for the code you wrote, and failing on a dependency's internals would
102
+ make the default-on checker unusable with packages.
103
+
104
+ ## Behaviour without the checker
105
+
106
+ `--no-check` restores the previous permissive pipeline: type syntax is erased
107
+ and lowering continues. It also restores the silent `Duplicate identifier`
108
+ behaviour (`let value = 1; let value = 2;` compiles and the first value wins).
109
+ Prefer keeping the checker on.
110
+
111
+ ## Cache and diagnostics
112
+
113
+ `check` is part of the incremental cache key, so a `--no-check` build never
114
+ reuses a checked artifact (or vice versa). With the checker on, code generation
115
+ does not repeat its own `Cannot find name` error, so each name is reported
116
+ exactly once. `xbintsc check` runs the checker and stops before linking; it is
117
+ the fast gate for editors and pre-commit hooks.
@@ -9,11 +9,18 @@ Location: `src/cli/main.ts`, `src/index.ts`, `bin/xbintsc.js`
9
9
  ```
10
10
  xbintsc build <file.ts> [options] compile to a native binary
11
11
  xbintsc run <file.ts> [-- args] compile and run
12
+ xbintsc check <file.ts> parse, bind and check without linking
13
+ xbintsc watch <file.ts> rebuild on source-tree changes
12
14
  xbintsc emit <file.ts> print LLVM IR
15
+ xbintsc doctor report the resolved toolchain
13
16
  xbintsc version print the version
14
17
  xbintsc help help
15
18
  ```
16
19
 
20
+ `check`, `emit`, `build`, `run` and `watch` all run the semantic checker by
21
+ default; `--no-check` skips it (and is part of the cache key). See
22
+ [the checker page](./checker.md).
23
+
17
24
  ## CLI options
18
25
 
19
26
  ```
@@ -31,6 +38,9 @@ xbintsc help help
31
38
  --app-id <id> macOS bundle identifier (e.g. com.example.demo)
32
39
  --force Ignore the incremental cache
33
40
  --verbose Print progress information
41
+ --debug Emit DWARF/CodeView debug info
42
+ --check Run the semantic checker (default)
43
+ --no-check Skip the semantic checker
34
44
  ```
35
45
 
36
46
  ## Programmatic API
@@ -38,8 +48,10 @@ xbintsc help help
38
48
  ```ts
39
49
  import { build, compileString } from "xbintsc";
40
50
 
41
- const { ir } = compileString("console.log(1 + 1);");
51
+ const { ir, diagnostics } = compileString("console.log(1 + 1);");
42
52
  const result = build("program.ts", { emit: "exe", outDir: "build" });
53
+ // The checker can be disabled per call, exactly like `--no-check`:
54
+ build("program.ts", { check: false });
43
55
  ```
44
56
 
45
57
  The option and result types (`BuildOptions`, `BuildResult`, `EmitKind`,
@@ -23,8 +23,9 @@ Location: `src/codegen/llvm.ts`
23
23
  - Optional chaining `?.` / `?.[]` / `?.()`: nullish check short-circuits to `undefined`
24
24
  - `delete`, `in`, `instanceof`
25
25
  - `this` (saved to the function's `%saved.this`; arrow functions read from an environment slot), `super` (`super.x` / `super(...)`), `new`, `await`
26
- - Closures (arrow functions / function expressions) and capture environment construction
27
- - Classes: constructor closure + prototype object, stored in an LLVM global (`@class.<id>`); instance fields are initialized before the constructor body; `static` members live in the constructor's property bag; `extends` sets up the prototype chain; `super(...)` is invoked through a hidden `__ctor` on the prototype.
26
+ - Destructuring: a binding-pattern default (`const { a = f() } = o`) is emitted as a branch, so `f()` runs only when the property is `undefined` — never eagerly
27
+ - Closures (arrow functions / function expressions / function declarations) and capture environment construction: a capture is the symbol's *box*, so writes inside the closure reach the enclosing binding. A declared function called by name builds its environment at the call site (`fn.captures` / `fn.capturesThis` disable the direct-call fast path); otherwise it would run with a null environment and read every free variable as `undefined`.
28
+ - Classes: constructor closure + prototype object, stored in an LLVM global (`@class.<id>`); instance fields are initialized before the constructor body; `static` members live in the constructor's property bag; `extends` sets up the prototype chain; `super(...)` is invoked through a hidden `__ctor` on the *parent* prototype. The parent is derived from the class being defined (`getPrototype(getPrototype(@class.N))`), never from the receiver: walking `this` resolves to the wrong class once an instance of a subclass calls a base constructor, which recurses forever in a chain deeper than two levels.
28
29
  - `async` / `async function*`: closures are marked with `xt_function_set_async` / `xt_function_set_async_generator` and run on stackful coroutines — see [Async, promises and generators](./async.md).
29
30
  - Standard library calls dispatch through `xt_call_method` / `xt_math_call` / `xt_object_*` and the per-constructor `xt_*` entry points; the surface is listed in [Standard library](./stdlib.md).
30
31
  - Global string pool (`@.str.N` private constants, UTF-8 escaped).
@@ -7,8 +7,8 @@ Location: `src/driver/compiler.ts` (orchestration), `src/driver/frontend.ts`,
7
7
  `src/driver/app-artifacts.ts`, `src/driver/cache.ts`, `src/driver/toolchain.ts`,
8
8
  `src/driver/paths.ts`, `src/driver/version.ts`.
9
9
 
10
- - Compilation pipeline: read source → module bundling (`src/driver/modules.ts`, when the entry contains `import`/`export`) → parse → bind/check → IR → object file → link.
11
- - Incremental cache: keyed on "compiler version + source hash + emit kind + optimization level + LTO/PGO mode + platform + extension fingerprint (names, linker flags, native object contents)"; if the artifacts exist and are fresh, the build is skipped. `--pgo-use` always rebuilds because the profile data can change without the source. The key is assembled in `src/driver/build-key.ts`.
10
+ - Compilation pipeline: read source → module bundling (`src/driver/modules.ts`, when the entry contains `import`/`export`) → parse → bind → [semantic check](./checker.md) → IR → object file → link.
11
+ - Incremental cache: keyed on "compiler version + source hash + emit kind + optimization level + LTO/PGO mode + platform + `check`/`no-check` + extension fingerprint (names, linker flags, native object contents)"; if the artifacts exist and are fresh, the build is skipped. `--pgo-use` always rebuilds because the profile data can change without the source. The key is assembled in `src/driver/build-key.ts`.
12
12
  - C runtime and extension sources are cached as object files by content hash and compiled only once (the cache key includes the LTO/PGO flags). `RUNTIME_SOURCES` in `src/driver/runtime-objects.ts` lists the core translation units.
13
13
  - Toolchain wrapper: locates `clang` (overridable with `xbintsc_CLANG`), compiles IR, compiles C, links.
14
14
  - LTO (`--lto` / `"lto": true`): the program and runtime compile to LLVM bitcode (`-flto`) and link with `-fuse-ld=lld`; lld is required.
@@ -30,7 +30,8 @@ Location: `src/codegen/llvm.ts` (`BINARY_RUNTIME`, `emitPrefix`, `emitPostfix`,
30
30
 
31
31
  ## Other expression operators
32
32
 
33
- - Comma expression `,`
33
+ - Comma expression `,` (lowers to a `SequenceExpression`: every operand is
34
+ evaluated left to right and the value of the last one is the result)
34
35
  - `in` operator (`key in obj`, mapped to `xt_in`)
35
36
  - `delete obj.key` / `delete obj[key]` (mapped to `xt_delete`)
36
37
  - `instanceof` (mapped to `xt_instance_of`, walking the prototype chain)
@@ -10,7 +10,7 @@ Module syntax (`import` / `export`, import attributes) and the driver-level bund
10
10
 
11
11
  - Variable declarations: `var` / `let` / `const`, with multiple declarators `const a = 1, b = 2;`
12
12
  - Function declarations, function expressions and methods, including the `async` modifier, generators (`function*`, `yield`, `yield*`, `.next`/`.throw`/`.return`) and async generators (`async function*`, `for await...of`)
13
- - `class` declarations / class expressions (constructor, fields, methods, `static`, `extends`)
13
+ - `class` declarations / class expressions (constructor, fields, methods, `static`, `static { ... }` blocks, `extends`)
14
14
  - `if` / `else`
15
15
  - `while`, `do...while`
16
16
  - `for` (init, condition and increment may all be omitted)
@@ -27,8 +27,9 @@ Module syntax (`import` / `export`, import attributes) and the driver-level bund
27
27
  - All common operators with precedence / associativity (see [Operators](./operators.md))
28
28
  - Assignment expressions and all compound assignments (see [Operators](./operators.md))
29
29
  - Conditional (ternary) expressions `a ? b : c`
30
+ - Comma / sequence expressions `a, b, c` (in `for` headers, parenthesized groups and expression statements)
30
31
  - Arrow functions `() => expr` / `() => { ... }` (including type parameters and return type annotations)
31
- - Function expressions `function () {}` and named function expressions `function g() {}`
32
+ - Function expressions `function () {}` and named function expressions `function g() {}` (also `async function` expressions)
32
33
  - Call expressions `f(...)`, member access `a.b`, element access `a[i]`
33
34
  - Array literals `[1, 2]`, sparse array elision, spread `[...a]` (also over strings, `Map` and `Set`)
34
35
  - Object literals `{ a: 1 }`, shorthand properties `{ a }`, method shorthand `{ m() {} }`, getter / setter shorthand `{ get x() {} }` / `{ set x(v) {} }`, computed keys `{ [expr]: 1 }`, object spread `{ ...obj }`