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
@@ -2,11 +2,27 @@
2
2
 
3
3
  > Part of [Unimplemented syntax and features](../unimplemented.md) · [简体中文](../zh-CN/unimplemented/types.md)
4
4
 
5
- Type syntax is parsed into the AST and then **erased entirely** during binding /
6
- code generation; no type checking is performed:
7
-
8
- - Type annotations, return types, type parameters, type aliases, interfaces, generic constraints, etc.: parse ✓, check ✗.
9
- - Checker diagnostic codes (`TypeMismatch` `NotCallable` `PropertyNotFound` `ArgumentCountMismatch`) are defined but **unused**.
10
- - `as` / `satisfies` / non-null assertion `!`: erased directly, no assertion semantics.
11
- - Generics: no runtime instantiation; type parameters are ignored.
12
- - Optional chaining `?.` type narrowing: none (runtime short-circuit is implemented, but there is no type-level narrowing).
5
+ Type syntax is **not** erased blindly any more: the default
6
+ [semantic checker](../implemented/checker.md) resolves the subset of TypeScript
7
+ types it can model and checks assignability, property existence and simple flow
8
+ narrowing. Type syntax is still erased during code generation, and the checker
9
+ is deliberately incomplete:
10
+
11
+ - **No full inference.** An unannotated function returns `any`; generic
12
+ constraints, higher-order inference and return-type inference are not
13
+ attempted.
14
+ - **No strict-null mode.** `null` / `undefined` are assignable wherever a value
15
+ is expected.
16
+ - **No excess-property check** on fresh object literals.
17
+ - **No overload resolution, mapped types, conditional types or template-literal
18
+ types.** They resolve to `any`.
19
+ - **`as` / `satisfies` / non-null `!`** are still erased and do not validate
20
+ anything; the checker treats them as assertions.
21
+ - **Complex generics.** Simple type parameters are inferred from arguments
22
+ (`T`, `T[]`, `Array<T>`); mapped/conditional generic machinery is not.
23
+ - **Type arguments are not checked for arity**; an unknown type parameter is
24
+ just `any`.
25
+
26
+ All six checker diagnostic codes are now used: `DuplicateIdentifier` (TS3001),
27
+ `CannotFindName` (TS3002), `TypeMismatch` (TS4001), `NotCallable` (TS4002),
28
+ `PropertyNotFound` (TS4003) and `ArgumentCountMismatch` (TS4004).
@@ -25,7 +25,7 @@ under [implemented](./implemented.md); git history records when it changed.
25
25
  - [Module system](./unimplemented/modules.md) — circular dependencies, live bindings, CommonJS boundaries
26
26
  - [Functions](./unimplemented/functions.md) — missing function semantics
27
27
  - [Classes and OO](./unimplemented/classes.md) — access control, `abstract`/`implements`, private-name collisions
28
- - [Type system](./unimplemented/types.md) — parsed but never checked
28
+ - [Type system](./unimplemented/types.md) — parsed and erased; only inference-free facts are checked
29
29
  - [Runtime deviations](./unimplemented/deviations.md) — compiles and runs, but differs from ECMAScript
30
30
  - [Toolchain and platform](./unimplemented/toolchain.md) — type checker, async I/O, GC modes, platform gaps
31
31
  - [Node extension](./unimplemented/node.md) — Node module gaps, one page per area
@@ -34,6 +34,47 @@ API 编写的文档可以原样运行。
34
34
  `ready`(首个呈现帧之后)、`load`、`close`、`resize`,以及输入事件
35
35
  `mousemove`、`mousedown`、`mouseup`、`click`、`wheel`、`keydown`、`keyup`。
36
36
 
37
+ ## 浏览器全局
38
+
39
+ 从 Web 迁移过来的页面很少只用到 `createWindow`。启用 `--ext gui` 后,运行时同样提供
40
+ 这类移植需要的那一层浏览器接口,程序不必自己声明:
41
+
42
+ ```ts
43
+ const ctx = new AudioContext(); // 也可 window.AudioContext
44
+ ctx.createGain().connect(ctx.destination);
45
+ document.querySelector("#start").addEventListener("click", () => {});
46
+ console.log(navigator.userAgent, window.innerWidth, location.href);
47
+ requestAnimationFrame(frame);
48
+ ```
49
+
50
+ | 全局 | 取值 |
51
+ | --- | --- |
52
+ | `window`、`self` | 最近打开的窗口句柄(若程序尚未创建窗口,会隐式打开一个),因此 `window.innerWidth`、`window.addEventListener`、`window.setTimeout`、`window.localStorage`、`window.location`、`window.devicePixelRatio`、`window.matchMedia` 都可用 |
53
+ | `document` | 该窗口的 document 句柄 |
54
+ | `navigator` | `userAgent`(以 `xbintsc` 结尾的桌面 Chrome 字符串)、`platform`、`vendor`、`language(s)`、`hardwareConcurrency`、`maxTouchPoints`、`onLine`、`vibrate()` |
55
+ | `localStorage` | 内存中的 `getItem` / `setItem` / `removeItem` / `clear` / `key` / `length` |
56
+ | `AudioContext`、`webkitAudioContext` | Web Audio 图构建器(见下) |
57
+ | `Event`、`CustomEvent`、`ProgressEvent` 等 | 事件构造器 |
58
+ | `HTMLCanvasElement`、`HTMLImageElement`、`ImageBitmap`、`ImageData`、`OffscreenCanvas`、`WebGL*`、`XRWebGL*`、`Request`、`Headers`、`Response`、`ReadableStream`、`DOMParser` | `typeof` 探测返回 `"undefined"`(引擎没有 WebGL、XR、fetch 或流式后端),让页面走自己的“不支持”分支,而不是调用空壳 |
59
+ | `requestAnimationFrame` / `cancelAnimationFrame` | 排入窗口的动画帧列表,见[运行时集成](./runtime.md) |
60
+ | `alert` / `confirm` / `prompt`、`matchMedia`、`getComputedStyle`、`escape` | 宿主实现(Annex B `escape` 按 UTF-16 码元编码,与 `decodeURIComponent(escape(bytes))` 一致) |
61
+
62
+ `getElementById` / `querySelector` 在 `loadHTML` 之前也能回答:此时得到的是**挂起**句柄,
63
+ 首次使用时才绑定到真实节点,因此在模块初始化阶段缓存 `document.querySelector("#id")`
64
+ 的页面依然可用。页面解析完成后未命中则回答 `undefined`,与浏览器一致。
65
+
66
+ ### Web Audio
67
+
68
+ `new AudioContext()` 会构建音频图,但**不做混音也不渲染音频**:背后没有后端。已实现的是
69
+ 页面运行与自检所需的接口 —— `createGain` / `createOscillator` / `createBufferSource` /
70
+ `createBiquadFilter` / `createDynamicsCompressor` / `createBuffer`(真实的
71
+ `Float32Array` 声道)/ `decodeAudioData`(以空缓冲区兑现)/ `resume` / `suspend` /
72
+ `close`,`AudioParam` 的 `value` 与 `setValueAtTime` / `linearRampToValueAtTime` /
73
+ `exponentialRampToValueAtTime` / `setTargetAtTime` / `cancelScheduledValues` /
74
+ `cancelAndHoldAtTime`,节点 `connect`(返回目标节点,因此可链式连接)/ `disconnect` /
75
+ `start` / `stop`。`sampleRate` 为 48000、`state` 为 `"running"`,`currentTime` 仅随
76
+ 事件循环推进。
77
+
37
78
  输入处理器接收单个负载对象(生命周期处理器不接收任何参数):
38
79
 
39
80
  ```ts
@@ -5,33 +5,39 @@
5
5
  > 属于 [GUI 扩展](../gui.md) 的一部分;引擎总览、锁定决策与路线图在那里。
6
6
 
7
7
  - 源码位于 `runtime/ext_gui/`(C/C++),外加 `vendor/` 下的 vendored 库
8
- (被 gitignore;按需获取)。
8
+ (被 gitignore;按需获取)。媒体解码位于 `runtime/ext_media/`,单独构建。
9
9
  - `npm run gui`(`scripts/build-gui.ts`)获取固定版本的 SDL3(`SDL3_TAG`,
10
10
  默认 `release-3.2.10`),构建静态 SDL3,获取并构建静态 FreeType
11
11
  (`FREETYPE_VERSION`)与 HarfBuzz(`HARFBUZZ_VERSION`),编译引擎,并把
12
12
  所有内容合并到 `runtime/lib/<os>-<arch>/gui.a`(Windows 上 MSVC ABI 则为
13
- `gui.lib`),与 `core.a` 采用相同约定,静态打包三者。它还会获取、配置并构建
14
- 一个最小化的静态 **FFmpeg**(`FFMPEG_VERSION`,默认 `7.1`),只启用媒体元素
15
- 所需的 demuxer/parser/decoder,并把那些归档合并进 `gui.a`,同时为引擎定义
16
- `XT_GUI_WITH_FFMPEG`。合并使用 macOS 上的
13
+ `gui.lib`),与 `core.a` 采用相同约定,静态打包三者。合并使用 macOS 上的
17
14
  `libtool` 与其他平台上的 `ar -M`(GNU/LLVM);CMake 归档会在构建根目录或
18
15
  `Release/` 下按任一生成器风格被发现。
19
- - `src/extensions/gui/index.ts` 通过 `nativeObjects()` 暴露该归档(经由
16
+ - `npm run media`(`scripts/build-media.ts`)构建可选的 **FFmpeg** 后端。它获取
17
+ FFmpeg(`FFMPEG_VERSION`,默认 `7.1`),配置一个只启用媒体元素所需
18
+ demuxer/parser/decoder 的最小静态构建,用它编译
19
+ `runtime/ext_media/media.cpp`,并把所有内容合并到
20
+ `runtime/lib/<os>-<arch>/media.a`。`gui.a` **不会**链接 FFmpeg:程序通过
21
+ `--ext media` 显式启用播放能力。
22
+ - `src/extensions/gui/index.ts` 通过 `nativeObjects()` 暴露引擎归档(经由
20
23
  `findRuntimeLibrary`,因此 `.a`/`.lib` 都可用),并通过 `linkerFlags()`
21
- 暴露操作系统框架。
24
+ 暴露操作系统框架。`src/extensions/media/index.ts` 对 `media.a` 做同样的暴露,
25
+ 并把注册桥(`runtime/ext_media/media_bridge.c`)作为普通 runtime 源编译。
22
26
  - `scripts/build-gui.ts` 使用与驱动**相同**的 clang
23
27
  (`src/driver/toolchain-provider.ts`);Windows 上就是 Visual Studio 自带的、
24
28
  面向 MSVC 的 LLVM,并配套使用其同目录下的 `clang++`/`llvm-ar` 来配置 CMake、
25
29
  编译引擎和合并归档。脚本不提供 `gcc`/`g++` 回退,Windows 上也始终使用
26
30
  `llvm-ar`,因此归档不会混入其他目标文件格式或 C++ 运行时。Visual Studio
27
31
  工具链按绝对路径查找,无需开发者命令提示符。Windows 上 SDL_GPU 会选择 Vulkan
28
- 后端,不需要 DXIL/`dxc` 工具链。
29
- - CI 在组装发布归档之前构建 `gui.a`,因此它会随 `runtime/lib/<slug>/` 一起
30
- 发布(发布 tarball 会复制整个 `runtime/` 树)。归档在 Linux(Xvfb 下,
31
- 使用 lavapipe 软件 Vulkan 驱动)与 macOS 上构建并运行示例;Windows 为
32
- 试验性,因为托管 runner 没有 GPU/Vulkan 驱动。
33
- - 现有的缓存指纹已经会对 `nativeObjects()` 的内容做哈希,因此重建 `gui.a`
34
- 会自动使缓存二进制失效。
32
+ 后端,不需要 DXIL/`dxc` 工具链。`scripts/build-media.ts` 对 FFmpeg 与播放器
33
+ 使用同一套已解析的工具链。
34
+ - CI 在组装发布归档之前构建 `gui.a` 与 `media.a`,因此它们会随
35
+ `runtime/lib/<slug>/` 一起发布(发布 tarball 会复制整个 `runtime/` 树)。
36
+ 归档在 Linux(Xvfb 下,使用 lavapipe 软件 Vulkan 驱动)与 macOS 上构建并运行
37
+ 示例;Windows 为试验性,因为托管 runner 没有 GPU/Vulkan 驱动,且 media 归档
38
+ 目前仅支持 POSIX。
39
+ - 现有的缓存指纹已经会对 `nativeObjects()` 的内容与 `runtimeSources()` 的内容
40
+ 做哈希,因此重建任一归档都会自动使缓存二进制失效。
35
41
  - CMake 构建树位于其源码**旁边**(`vendor/sdl-build`、`vendor/freetype-build`、
36
42
  `vendor/harfbuzz-build`),绝不放在源码内部:`CMakeCache.txt` 记录的是配置它
37
43
  的那台机器,而 SDL 的视频后端是 `option()`,因此先运行的那次配置会一直生效。
@@ -47,6 +53,7 @@
47
53
  ```sh
48
54
  npm run runtime # runtime 改动后重建 core.a
49
55
  npm run gui # 构建 runtime/lib/<os>-<arch>/gui.a(首次会获取 SDL3)
56
+ npm run media # 可选:构建 media.a(首次会获取并构建 FFmpeg)
50
57
  xbintsc run examples/gui/hello.ts --ext gui
51
58
  ```
52
59
 
@@ -59,8 +66,9 @@ xbintsc run examples/gui/hello.ts --ext gui
59
66
 
60
67
  `examples/gui/media.ts`(配合 `media.html`)演示 `<video>`/`<audio>`:它在
61
68
  `<video>` 上叠一个 CSS 进度条,并用 `play()`/`pause()`/`currentTime`/
62
- `volume` 驱动播放。媒体 `src` 相对于进程工作目录解析,因此从仓库根目录运行:
63
- `xbintsc run examples/gui/media.ts --ext gui`。几何报告见该目录的 README。
69
+ `volume` 驱动播放。它需要单独的可选 `media` 扩展,因此要构建并同时启用两者。
70
+ 媒体 `src` 相对于进程工作目录解析,因此从仓库根目录运行:
71
+ `xbintsc run examples/gui/media.ts --ext gui,media`。几何报告见该目录的 README。
64
72
 
65
73
  这些测试套件在 Windows 上默认跳过(归档可以在本机通过 Vulkan 运行,但 CI
66
74
  runner 没有可用的 GPU 驱动)。如果本机有 `gui.lib` 与可用的 GPU,可用
@@ -77,10 +85,14 @@ npx vitest run tests/e2e/gui-layout.test.ts tests/e2e/gui-example.test.ts
77
85
  ```sh
78
86
  sudo sh scripts/install-gui-deps.sh # clang、cmake、X11/Wayland 头文件、Vulkan、Xvfb
79
87
  npm run runtime && npm run gui
88
+ npm run media # 可选:<video>/<audio> 播放
80
89
  xvfb-run -a --server-args="-screen 0 1280x720x24" \
81
90
  npx tsx src/cli/main.ts run examples/gui/hello.ts --ext gui
82
91
  ```
83
92
 
93
+ 媒体 e2e 套件(`tests/e2e/gui-media.test.ts`)只有在 `gui.a` 与 `media.a` 都
94
+ 存在时才会运行;`tests/e2e/gui-media-disabled.test.ts` 覆盖仅 `gui.a` 的构建。
95
+
84
96
  包清单集中在 `scripts/install-gui-deps.sh`(`apt-get install -y clang cmake
85
97
  libx11-dev libxext-dev libxrandr-dev libxcursor-dev libxi-dev libxinerama-dev
86
98
  libxfixes-dev libxkbcommon-dev libwayland-dev wayland-protocols libdecor-0-dev
@@ -6,6 +6,13 @@
6
6
 
7
7
  ## 已知问题
8
8
 
9
+ - **没有 WebGL。** `getContext("webgl")` / `getContext("webgl2")` 返回 `null`,
10
+ `WebGL*` / `WebGL2RenderingContext` / `XRWebGL*` 全局为 `undefined`,因此像 Three.js
11
+ 场景这样的 WebGL 页面会以库自身的 “Error creating WebGL context” 失败,应当显示自己的
12
+ 降级面板。只有 `getContext("2d")` 由光栅器支撑(见[画布](./canvas.md))。移植页面
13
+ 的其余部分——模块图、DOM 句柄、事件、[API](./api.md) 中的浏览器全局、帧泵——都能工作,
14
+ 所以 Three.js 程序**可以编译并启动**,只是无法绘制。
15
+
9
16
  - **自动关闭时的偶发崩溃。** 设置 `XT_GUI_AUTOCLOSE_MS` 结束运行时,约五次中有两次会以原生
10
17
  访问违例(`0xC0000005`)退出,其余运行与正常退出无异。该问题只在**动画帧循环运行中**复现
11
18
  (静态文档可以正常关闭),且**不是示例游戏自身**的代码:没有任何异常信息,崩溃多发生在
@@ -54,11 +61,12 @@
54
61
  SDL_GPU 会选择 **Vulkan** 后端(`win.driver()` 返回 `"vulkan"`),因此归档
55
62
  不需要 DXIL/`dxc` 工具链;托管 Windows runner 没有 GPU/Vulkan 驱动,这才是
56
63
  CI 运行仍为试验性的原因。
57
- - **Windows 上的媒体:** 媒体解码器(FFmpeg)只构建并合并进 POSIX 的
58
- `gui.a`;Windows 的 `gui.lib` 不含它们,因此那里的 `<video>`/`<audio>` 为空
59
- 操作(失败会触发 `error`)。启用它需要 MSVC 兼容的 FFmpeg 构建,推迟到
60
- Windows GUI 路径本身验证之后。`<video controls>` 同样推迟——预期模式是 TS +
61
- CSS 叠层,如 `examples/gui/media.ts`。
64
+ - **Windows 上的媒体:** `media` 扩展目前仅支持 POSIX。GUI 引擎本身可在
65
+ Windows 上构建,但没有该扩展时 `<video>`/`<audio>` 为空操作(打开失败并触发
66
+ `error`),`--ext media` 会给出可操作的错误而不是继续链接。启用它需要
67
+ MSVC 兼容的 FFmpeg 构建,推迟到 Windows GUI 路径本身验证之后。
68
+ `<video controls>` 同样推迟——预期模式是 TS + CSS 叠层,如
69
+ `examples/gui/media.ts`。
62
70
  - **D3D12 着色器:** SPIR-V(Vulkan)与 DXIL(Direct3D 12)二进制块均已构建并
63
71
  内嵌,非 Metal 路径不再跳过几何绘制。但在 **SDL 3.2.10** 上 DXIL 仍不可用:
64
72
  其 D3D12 后端会拒绝任何着色器中声明了 uniform buffer 的图形管线,而引擎正是
@@ -55,25 +55,36 @@ opacity、`display`——与任何其他元素一样。盒子内部的艺术内
55
55
 
56
56
  ## 视频与音频(M13)
57
57
 
58
- `runtime/ext_gui/media.{h,cpp}` 封装一个静态 vendored 的 **FFmpeg** 构建,
59
- `runtime/ext_gui/gui_media.cpp` 把 DOM 树接到它上面。`<video>` 与 `<audio>`
60
- 真正解码并播放;路径中没有 WebView,也没有平台媒体框架。
58
+ 媒体播放横跨两个扩展,因此只做界面的 GUI 程序不必为用不到的解码器付出体积:
59
+
60
+ - **`gui`**(`gui.a`)负责 `<video>`/`<audio>` 元素、DOM API、渲染器集成与 SDL
61
+ 音频 sink,但**不含 FFmpeg**。`runtime/ext_gui/media.{h,cpp}` 声明播放器接口,
62
+ 并通过媒体后端在启动时安装的函数表分发(`runtime/ext_gui/media_api.h`)。
63
+ - **`media`**(`media.a`、`runtime/ext_media/`)是可选的解码后端:
64
+ `runtime/ext_media/media.cpp` 封装静态 vendored 的 **FFmpeg** 构建,
65
+ `runtime/ext_media/media_bridge.c` 把它注册进引擎。用 `--ext media`(或
66
+ `--ext gui,media`)启用。`media` 依赖 `gui`;注册表会拒绝错误的组合。
67
+
68
+ 没有 `media` 扩展时,元素仍然存在、DOM API 仍可调用,但打开源会失败并触发
69
+ `error`。Windows 目前也是如此:该归档仅支持 POSIX。两条路径都没有 WebView,也
70
+ 没有平台媒体框架。
61
71
 
62
72
  - **解码。** `avformat_open_input` 打开 `src`(是路径——接受 `file://`,但与
63
73
  图像不同,媒体路径*不做*百分号解码),为每种媒体选取最佳流,软件解码器
64
74
  产出 `yuv/rgb` 帧,`sws_scale` 按编码尺寸转换为 RGBA8。支持的容器/编码即
65
- `scripts/build-gui.ts` 的最小 FFmpeg 配置:MP4/MOV/MKV/AVI/FLV/MPEG-TS/M4V/
75
+ `scripts/build-media.ts` 的最小 FFmpeg 配置:MP4/MOV/MKV/AVI/FLV/MPEG-TS/M4V/
66
76
  ASF,MP3/OGG/WAV/FLAC/AAC;视频 H.264、HEVC、VP8、VP9、AV1、MPEG-4、MJPEG;
67
77
  音频 AAC、MP3、Opus、Vorbis、FLAC、ALAC、AC3/E-AC3、WMAv2 及原始 PCM 格式。
68
78
  - **视频。** `<video>` 与 `<img>` 一样是替换元素(UA 默认 `300x150`,解码
69
79
  尺寸通过 `setMediaSize` 覆盖)。绘制产出与图像相同的 `PaintImage`;渲染器把
70
80
  每个新解码帧上传到 RGBA 纹理(`ensureMediaTexture`)并绘制带纹理四边形,
71
- 因此由 GPU 缩放到 CSS 盒,而非 CPU 缩放。播放计时基于墙钟
72
- (`SDL_GetTicks`),不是帧间隔。
73
- - **音频。** 没有音频回调:解码器随主线程 tick 被推送,PCM 以 push 模式
74
- (`NULL` 回调)通过 `SDL_OpenAudioDeviceStream` 排队,在前方缓冲约 0.25 秒,
75
- 格式为 48 kHz 立体声 `SDL_AUDIO_F32`。`volume` 映射到
76
- `SDL_SetAudioStreamGain`;音频是尽力而为,无设备时(无头 CI)跳过。
81
+ 因此由 GPU 缩放到 CSS 盒,而非 CPU 缩放。播放计时基于进程单调时钟,不是帧间隔。
82
+ - **音频。** 没有音频回调:解码器随主线程 tick 被推送,并写入
83
+ `xtgui::AudioSink`。GUI 在 `gui_media.cpp` 中用 push 模式(`NULL` 回调)的
84
+ `SDL_OpenAudioDeviceStream` 实现该 sink,在前方缓冲约 0.25 秒,格式为
85
+ 48 kHz 立体声 `SDL_AUDIO_F32`。`volume` 映射到 `SDL_SetAudioStreamGain`;
86
+ 音频是尽力而为,无设备时(无头 CI)跳过。把 sink 留在 `gui.a` 中意味着
87
+ `media.a` 只依赖 FFmpeg。
77
88
  - **线程。** 引擎是单线程且非线程感知,因此所有解码都在主线程的
78
89
  `xt_gui_media_tick` 内完成——没有解码线程,也没有跨线程 GC 暴露。
79
90
  - **DOM API。** 元素句柄直接暴露媒体接口(见
@@ -27,6 +27,22 @@ GUI 引擎既可以通过 `xt_loop_set_main` 注册自己的循环,也可以
27
27
 
28
28
  `xt_loop_set_main` 钩子仍保留给希望自行掌控循环的宿主。
29
29
 
30
+ ### 帧泵(从不调用 `run()` 的页面)
31
+
32
+ 为浏览器编写的页面不会调用 `run()`;它调用 `requestAnimationFrame`,期望宿主
33
+ 负责绘制。`browser_loop.cpp` 用一个 16 ms 的 `xt_set_timeout` tick 覆盖这种情形:
34
+
35
+ - 它在 `loadHTML` 时启动,而不是在第一次 `requestAnimationFrame` 时启动 ——
36
+ `ready` 由第一次**真正呈现**的帧触发,若等待页面的回调就会死锁;
37
+ - 每个 tick 派发待处理输入,渲染每个打开的窗口(渲染会在布局前清空已排队的
38
+ 动画帧回调,因此页面可以自行停止);
39
+ - 只有在**仍有回调**时才重新排程,空闲页面会让事件循环排空并退出进程 ——
40
+ 这正是浏览器标签页的生命周期;
41
+ - 当 `xt_gui_run_active()` 为真(程序自己调用了 `run()`)时它会让路,避免同一
42
+ 窗口每 tick 被渲染两次;
43
+ - `XT_GUI_AUTOCLOSE_MS=n` 让帧泵在 `n` 毫秒后退出,测试用它来运行不会自行
44
+ 关闭的页面。
45
+
30
46
  这使网络 I/O、定时器与 `await` 在 GUI 程序内部继续工作。
31
47
 
32
48
  ## 原生 ↔ TS 桥接
@@ -159,6 +159,11 @@ export default __html;
159
159
  `src` URL(`https://…`、`data:…`、`//host`)保持原样 —— 它们不是编译期资产,
160
160
  永不运行。
161
161
 
162
+ 被包装的脚本体以**它自己的文件**作为其中每条语句的来源(loader 会把该脚本体在生成模块中的
163
+ 区间作为 source range 上报),因此诊断会指向 `app.js:12`,而不是 `index.html` 的某一列;
164
+ 同时**纯 JavaScript** 脚本与直接 import 的 `.js` 模块一样不做类型检查:在对象字面量上写
165
+ `state.update = …` 不会再报 `TS4003`。页面因此可以原样携带已有的脚本。
166
+
162
167
  ```html
163
168
  <button id="b">0</button>
164
169
  <script src="./counter.ts"></script>
package/doc/zh-CN/gui.md CHANGED
@@ -3,9 +3,9 @@
3
3
  > 语言 / Language:[English](../gui.md) | **简体中文**
4
4
 
5
5
  状态:**M16** —— 功能(M1–M15)已全部完成:HTML 解析、CSS 选择器匹配、层叠(cascade)、计算样式与布局(块级、行内、Flexbox 与 CSS 定位)均已就位,引擎还会**绘制**:它构建一个由矩形、图像与排版后的文本 run 组成的显示列表,并通过 SDL_GPU 渲染。输入事件会经过命中测试并投递给原生 TS 处理器,`:hover`/`:focus` 会被动态匹配,`<img>` 依据其固有尺寸确定大小并从纹理绘制——位图(PNG/JPEG/…)与 SVG 文件皆可,后者按绘制尺寸光栅化,因此矢量图保持清晰——CSS transition 会为绘制属性做动画。**M16** 让内联 `<svg>` 子树获得同样的处理:子树被序列化回 SVG 文档,并按绘制设备尺寸光栅化,因此图标不再需要单独的文件。**M8** 增加了交互式 DOM:具有稳定标识的元素句柄、变更操作(`appendChild`、`textContent`、`classList`、`style` 等)以及支持捕获/冒泡的元素级事件。**M9** 会提前编译 `<script>` 主体(内联与 `<script src>`)——参见 `gui-scripts.md`。**M10** 增加 `requestAnimationFrame` 以及若干 DOM 辅助方法。**M11** 增加 `position: relative`/`absolute`/`fixed` 及其偏移,`examples/gui/pelican-bike`(一个可玩的 2D 游戏)就构建在它之上。**M12** 明确了 DOM 节点生命周期(哪些变更释放、哪些保留),并让引擎内存有界:参见[节点生命周期](./gui/dom.md)与[内存与 GC](./gui/runtime.md)。**M13** 真正播放
6
- `<video>`/`<audio>`——一个 vendored 的最小 FFmpeg 在主线程解码,视频帧走图像
7
- 纹理路径、音频进入 SDL 流,DOM 媒体 API 暴露 `play`/`pause`/`currentTime`/…
8
- 与媒体事件。**M14** 增加了 `<canvas>`,配一个自研的 2D 软件光栅器(抗锯齿
6
+ `<video>`/`<audio>`——可选的 `media` 扩展用 vendored 的最小 FFmpeg 在主线程解码,
7
+ 视频帧走图像纹理路径、音频进入 SDL 流,DOM 媒体 API 暴露
8
+ `play`/`pause`/`currentTime`/… 与媒体事件。只启用 `gui` 不会链接 FFmpeg。**M14** 增加了 `<canvas>`,配一个自研的 2D 软件光栅器(抗锯齿
9
9
  填充、路径、文本与 `drawImage`),并经图像纹理路径上传——参见
10
10
  [Canvas](./gui/canvas.md)。**M15** 增加了 CSS `transform` /
11
11
  `transform-origin`:每个布局盒一个合成好的 `Matrix2D`,由显示列表一路带到
@@ -52,7 +52,7 @@
52
52
  | 4 | 引擎**非自托管**(它是 C/C++,不是 TS),但不得影响编译器的平台无关设计。以按平台预构建的归档形式交付,通过 `nativeObjects` 链接。 |
53
53
  | 5 | **事件循环是通用的**:运行时暴露一个通用主循环钩子与一个轮询原语;任何 GUI 特定的东西都不会进入 `runtime/`。 |
54
54
  | 6 | 核心对象模型支持**多窗口**。 |
55
- | 7 | 第三方底层库**静态链接进 `gui.a`**,使发布版保持自包含;链接时只额外加入操作系统框架。 |
55
+ | 7 | 第三方底层库**静态链接进扩展归档**,使发布版保持自包含;链接时只额外加入操作系统框架。`gui.a` 携带 SDL3/FreeType/HarfBuzz,可选的 `media.a` 携带 FFmpeg,仅在 `--ext media` 时链接。 |
56
56
 
57
57
  ## 架构
58
58
 
@@ -74,6 +74,7 @@
74
74
  窗口 + 输入(SDL3)── 多窗口
75
75
  文本(HarfBuzz + FreeType)── 字形图集 / SDF
76
76
  图像(stb_image;SVG 经 NanoSVG)
77
+ 媒体 DOM + 音频 sink ── 可选的 media.a(FFmpeg)安装解码器
77
78
  ```
78
79
 
79
80
  引擎从不与编译器通信。编译器只看到一个带有 `nativeObjects()`、`linkerFlags()` 和 `modules()` 的 `Extension`。
@@ -87,16 +88,16 @@
87
88
  | 文本整形 | **HarfBuzz** | 正确处理复杂文种的整形 |
88
89
  | 字形光栅化 | **FreeType** | 字形轮廓 → GPU 图集 / SDF |
89
90
  | 图像 | 位图用 **stb_image**(vendored 头文件),SVG 用 **NanoSVG**(vendored 头文件) | 起步阶段用单头文件;SVG 文件按需光栅化 |
90
- | 视频 + 音频 | **FFmpeg**(静态 vendored,最小化构建) | 解码常用容器/编码;不依赖 WebView 或平台媒体框架 |
91
+ | 视频 + 音频 | **FFmpeg**(静态 vendored,最小化构建,可选 `media` 扩展) | 解码常用容器/编码;不依赖 WebView 或平台媒体框架 |
91
92
 
92
93
  固定版本:SDL3 `release-3.2.10`、FreeType `2.13.3`、HarfBuzz `10.1.0`、
93
- FFmpeg `7.1`(可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
94
- `FFMPEG_VERSION` 覆盖)。
94
+ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
95
+ `FREETYPE_VERSION` / `HARFBUZZ_VERSION` / `FFMPEG_VERSION` 覆盖)。
95
96
 
96
97
  如果否决 SDL3,备选是 **GLFW + OpenGL 3.3**(更简单,但 OpenGL 在 macOS 上
97
98
  已弃用,且不提供现代 GPU 抽象)。如果引擎用 Rust 编写,则用 **wgpu-native**。
98
99
 
99
- > 这些 vendored 库会**静态链接进 `gui.a`**,因此发布的 xbintsc 保持
100
+ > 这些 vendored 库会**静态链接进 `gui.a` / `media.a`**,因此发布的 xbintsc 保持
100
101
  > “下载即用”;`linkerFlags()` 只添加操作系统框架。
101
102
 
102
103
  ## 里程碑
@@ -135,14 +136,15 @@ FFmpeg `7.1`(可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
135
136
  `background-color`/`color`/`border-color`/`border-radius` 的动画、重定向
136
137
  与 `win.advance(ms)`。`@keyframes` 仍待完成。
137
138
  7. **M7 — CI 与发布** ✅(Linux/macOS 构建) / 🚧(运行 + Windows)
138
- - `compile-examples` 在 Linux 与 macOS 上构建 `gui.a`(必需),然后在
139
- Linux 上的 Xvfb + lavapipe 下运行示例与 `tests/e2e/gui-*.test.ts`(必需)。
140
- macOS 运行在确认 WindowServer 之前为试验性;它被保护起来,失败只记录
141
- 日志而不标注运行。
142
- - `package` job 在组装发布之前构建 `gui.a`,因此它会随现有 runtime 归档
143
- 一起发布(`package-release` 复制整个 `runtime/`)。
144
- - `vendor/`(SDL3/FreeType/HarfBuzz,缓慢的部分)按 OS/arch 缓存,以
145
- `scripts/build-gui.ts` 为键。
139
+ - `compile-examples` 在 Linux 与 macOS 上构建 `gui.a` 与 `media.a`(必需),
140
+ 然后在 Linux 上的 Xvfb + lavapipe 下运行示例与 `tests/e2e/gui-*.test.ts`
141
+ (必需)。macOS 运行在确认 WindowServer 之前为试验性;它被保护起来,失败
142
+ 只记录日志而不标注运行。
143
+ - `package` job 在组装发布之前构建 `gui.a` 与 `media.a`,因此两者都会随现有
144
+ runtime 归档一起发布(`package-release` 复制整个 `runtime/`)。
145
+ - `vendor/`(`gui.a` 的 SDL3/FreeType/HarfBuzz,以及 `media.a` 的 FFmpeg,
146
+ 缓慢的部分)按 OS/arch 缓存,以 `scripts/build-gui.ts` /
147
+ `scripts/build-media.ts` 为键。
146
148
  - Windows(构建 + 运行)在 CI 中保持试验性:MSVC 兼容的 `gui.lib` 可在本机
147
149
  通过 SDL_GPU 的 Vulkan 后端构建并运行,但托管 runner 没有 GPU/Vulkan
148
150
  驱动。失败只记录日志而不标注运行(见[待决问题](./gui/known-issues.md))。
@@ -189,13 +191,14 @@ FFmpeg `7.1`(可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
189
191
  - `win.stats()` 暴露引擎计数器;e2e 覆盖见
190
192
  `tests/e2e/gui-retention.test.ts`(见[内存与 GC](./gui/runtime.md))。
191
193
  13. **M13 — 视频与音频** ✅
192
- - `<video>` / `<audio>` 通过静态 vendored 的最小 FFmpeg 解码
193
- (`media.*`、`gui_media.cpp`),帧沿用现有图像管线上传到 GPU 纹理,
194
- 音频在主线程推送进 SDL 流,并在元素句柄上暴露 DOM 媒体 API 与
195
- `loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error` 事件
196
- (`dom_api_media.cpp`、`dom_api_proto.cpp`)。由 TS + CSS 控制;没有
197
- 内置控件。示例见 `examples/gui/media.*`,e2e 见
198
- `tests/e2e/gui-media.test.ts`。
194
+ - `<video>` / `<audio>` 通过可选的 `media` 扩展(`runtime/ext_media/media.cpp`)
195
+ 使用静态 vendored 的最小 FFmpeg 解码,帧沿用现有图像管线上传到 GPU 纹理,
196
+ 音频由 GUI 的音频 sink 在主线程推送进 SDL 流,并在元素句柄上暴露 DOM
197
+ 媒体 API 与 `loadedmetadata`/`play`/`pause`/`ended`/`timeupdate`/`error`
198
+ 事件(`dom_api_media.cpp`、`dom_api_proto.cpp`)。由 TS + CSS 控制;没有
199
+ 内置控件。示例见 `examples/gui/media.*`;e2e 见
200
+ `tests/e2e/gui-media.test.ts`(启用 `media`)与
201
+ `tests/e2e/gui-media-disabled.test.ts`(不启用)。
199
202
  14. **M14 — `<canvas>` 2D** ✅
200
203
  - `<canvas>` 是一个替换元素(`xtgui::Canvas2D`、`layout.*`),
201
204
  `getContext("2d")` 句柄与绘制 API 位于 `dom_api_canvas.cpp`,自研的抗锯齿
@@ -249,10 +252,10 @@ FFmpeg `7.1`(可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
249
252
  按绘制设备像素尺寸光栅化并按该尺寸缓存,因此缩放与 HiDPI 保持清晰。
250
253
  - **M6b** ✅ CSS transition(在 `style.*` 中解析、在 `document.*` 中维护动画
251
254
  时钟与 transition 状态、`advance`/`advance(ms)` 钩子、e2e 覆盖)。
252
- - **M7** ✅ 在 CI 中于 Linux 与 macOS 上构建 `gui.a`(必需),并在 Linux 的
253
- Xvfb 下运行示例与 GUI e2e 套件;`package` 发布 `gui.a`,`vendor/` 被缓存,
254
- `ar -M` 合并在 GNU/Linux 与 macOS 上可用。macOS 运行与所有 Windows 在 CI
255
- 中仍为试验性。
255
+ - **M7** ✅ 在 CI 中于 Linux 与 macOS 上构建 `gui.a`(以及可选的 `media.a`,
256
+ 必需),并在 Linux 的 Xvfb 下运行示例与 GUI e2e 套件;`package` 发布两个归档,
257
+ `vendor/` 被缓存,`ar -M` 合并在 GNU/Linux 与 macOS 上可用。macOS 运行与所有
258
+ Windows 在 CI 中仍为试验性。
256
259
  - **M8** ✅ 元素/文档句柄(`dom_api.*`)、带延迟重算样式/重新布局的 DOM 变更
257
260
  (`document.*`、`xt_gui_flush_dom`)、带捕获/冒泡与 `stopPropagation` 的
258
261
  元素事件分发(`dom_api.*`、`gui.cpp`),以及
@@ -283,11 +286,13 @@ FFmpeg `7.1`(可用 `SDL3_TAG` / `FREETYPE_VERSION` / `HARFBUZZ_VERSION` /
283
286
  失效;收集器的触发阈值改为跟随存活集,而不再只升不降。`win.stats()` 暴露
284
287
  引擎计数器,`tests/e2e/gui-retention.test.ts` 对其做断言;每帧重写精灵的游戏
285
288
  循环现在内存恒定(见[内存与 GC](./gui/runtime.md))。
286
- - **M13** ✅ `<video>` / `<audio>` 支持。一个最小化的静态 FFmpeg 被 vendored
287
- 并合并进 `gui.a`(`scripts/build-gui.ts`),`media.*` 在主线程把视频解码为
288
- RGBA 帧、把音频解码为 48 kHz 立体声 PCM,`gui_media.cpp` 持有播放器并在每帧
289
- 推进媒体时钟与事件,`renderer_image.cpp` 把每个新视频帧沿图像纹理路径上传,
290
- `dom_api_media.cpp` 在元素句柄上暴露 `play`/`pause`/`load` 与媒体属性。
289
+ - **M13** ✅ `<video>` / `<audio>` 支持。可选的 `media` 扩展 vendored 并构建一个
290
+ 最小化的静态 FFmpeg(`scripts/build-media.ts`),合并进 `media.a`;
291
+ `runtime/ext_media/media.cpp` 在主线程把视频解码为 RGBA 帧、把音频解码为
292
+ 48 kHz 立体声 PCM,`runtime/ext_gui/gui_media.cpp` 持有播放器、实现 SDL 音频
293
+ sink 并在每帧推进媒体时钟与事件,`renderer_image.cpp` 把每个新视频帧沿图像纹理
294
+ 路径上传,`dom_api_media.cpp` 在元素句柄上暴露 `play`/`pause`/`load` 与媒体
295
+ 属性。`gui.a` 不含 FFmpeg;只启用 `media` 而不启用 `gui` 会被注册表拒绝。
291
296
  `examples/gui/media.*` 演示 TS + CSS 控件的模式,
292
297
  `tests/e2e/gui-media.test.ts` 对其做断言。
293
298
  - **M14** ✅ `<canvas>` 支持。新的替换元素(`layout.*`)从 `width`/`height`
@@ -7,6 +7,8 @@
7
7
  - 作用域种类:模块、函数、块、`for`、`catch`
8
8
  - 符号种类:`var` / `let` / `const` / `function` / `parameter` / `class` / `interface` / `type` / `enum` / `import` / `namespace`
9
9
  - `var` 与函数声明提升到函数作用域;`let` / `const` 保持块作用域
10
+ - `switch` 主体是一个共享块作用域:所有 `case` / `default` 子句中的声明会在绑定任意子句之前预先声明
11
+ - `static { ... }` 类静态块绑定为类的隐藏静态函数(见[类与面向对象](../unimplemented/classes.md))
10
12
  - 标识符 → 声明 的解析;未解析标识符收集(`CannotFindName`)
11
13
  - 闭包捕获分析:被内层函数引用的外部变量标记 `captured` / `boxed`,并穿过中间闭包传递捕获索引
12
14
  - 参数登记为局部符号;命名函数表达式自名登记为 `const`
@@ -0,0 +1,99 @@
1
+ # 语义检查
2
+
3
+ > 属于[已实现的语法与功能](../implemented.md) · [English](../../implemented/checker.md)
4
+
5
+ 位置:`src/checker/`(`checker.ts`、`undefined.ts`、`declarations.ts`、
6
+ `calls.ts`、`type-system.ts`、`assignability.ts`、`flow.ts`、`typecheck.ts`),
7
+ 由 `generate()` 在绑定之后、生成 LLVM IR 之前调用。
8
+
9
+ 检查器**默认开启**;`--no-check`(或编程接口里的 `check: false`)可以关闭。
10
+ 它把无需类型推断的检查与一个小型结构化类型模型结合起来:
11
+
12
+ | 诊断 | 错误码 | 检查内容 |
13
+ | --- | --- | --- |
14
+ | `Cannot find name` | TS3002 | 标识符既没有声明,也不是运行时全局 |
15
+ | `Duplicate identifier` | TS3001 | 同作用域内不能合并的重复声明(两次 `let x`、`function f` 后又 `const f`、`let` 与参数同名……) |
16
+ | `Argument count mismatch` | TS4004 | 直接调用本地可见函数或 `const` 箭头/函数表达式时,实参过少或过多 |
17
+ | `Property not found` | TS4003 | 在可静态确定的形状上读取不存在的属性 |
18
+ | `Type mismatch` | TS4001 | 初始化、赋值、返回值或调用实参确定不可赋值 |
19
+ | `Not callable` | TS4002 | 调用的值类型是原始类型(number、string、boolean……) |
20
+
21
+ ## 类型模型知道什么
22
+
23
+ 检查器解析它能理解的类型语法,其余全部当作 `any`:
24
+
25
+ - 关键字类型、字面量类型、`A | B` 联合与对象类型字面量;
26
+ - 接口与类型别名(含泛型别名与 `extends`);
27
+ - 类:实例字段、方法、访问器、参数属性、`this.x = ...` 成员与本地祖先类。
28
+ 静态成员不算实例成员;
29
+ - 数组、元组、函数类型、对象字面量与 `new LocalClass()`;
30
+ - 简单泛型:声明处的类型参数视为 `any`;调用时从实参推断(`T`、`T[]`、
31
+ `Array<T>`),或使用显式类型实参。
32
+
33
+ 模型叫不出名字的语法——映射/条件类型、`keyof`、`typeof` 查询、索引访问、
34
+ 工具类型、被打包重命名后无法解析的导入类型、未知基类——都变成 `any`。
35
+ `any` 与一切兼容,这是核心安全属性:不支持的语法最多隐藏一个 bug,
36
+ 绝不会拒绝能正常工作的代码。
37
+
38
+ ## 可赋值性
39
+
40
+ 在变量初始化、`=` 赋值、`return` 与调用实参处检查:
41
+
42
+ - 原始类型与字面量类型;
43
+ - 对象/接口/类形状:目标中每个必需属性都必须存在且可赋值;源可以有多余属性;
44
+ - 数组与元组逐元素检查;
45
+ - 函数:参数个数与返回类型(保守比较);
46
+ - 联合:源的每个成员都必须能匹配目标成员,或目标某个成员能接受源。
47
+
48
+ `let`/`var` 推断加宽后的类型(`let x = 1` 是 `number`),`const` 保留字面量。
49
+ `null` 与 `undefined` 在任何需要值的位置都被接受(没有 strict-null 模式)。
50
+ 函数返回类型不做推断:未标注返回类型的函数返回 `any`,因此调用方永远不会被误报。
51
+
52
+ ## 属性是否存在
53
+
54
+ 形状来自显式类型注解,或来自用对象字面量 / `new LocalClass(...)` 初始化的
55
+ `const`。可选属性、`Object.prototype` 成员(`toString`、`hasOwnProperty`……)、
56
+ 索引签名与继承的类成员都会被接受。
57
+
58
+ 当形状在声明后可能改变时,该变量会被放过:属性写/删/自增、可能修改它的调用
59
+ (`mutate(object)`、`Object.assign(object, ...)`)、别名(`const p = object`)、
60
+ 动态构造函数(`Object.assign(this, ...)`、`this[key] = ...`)或原型扩展
61
+ (`Object.assign(C.prototype, ...)`)。给不存在的属性赋值是允许的
62
+ (xbintsc 程序经常在字面量之后扩展对象);这次写入会把形状打开,而不是报错。
63
+
64
+ 不检查:`object["x"]` 下标访问、解构、经函数返回值得到的形状、
65
+ 经数组/对象容器产生的别名。
66
+
67
+ ## 类型收窄
68
+
69
+ 在分支内部,当条件是以下形式时检查器会收窄变量:
70
+
71
+ - `value !== null` / `!== undefined` / `!= null`(以及 `===` 形式);
72
+ - `typeof value === "string" | "number" | "boolean" | "bigint" | "symbol" | "undefined"`;
73
+ - `value instanceof LocalClass`;
74
+ - 真值判断(`if (value)`、`value &&`、`value ||`);
75
+ - 通过 `&&`、`||`、`??`、`!` 组合的形式。
76
+
77
+ `if`/`else` 与条件表达式(`cond ? a : b`)会应用收窄;其他控制流不会。
78
+
79
+ ## 刻意不检查什么
80
+
81
+ - 完整推断:未标注的函数返回类型、复杂泛型约束与高阶推断都按 `any` 处理。
82
+ - 新对象字面量的多余属性检查。
83
+ - `as`/`satisfies` 断言可自由收窄或放宽(它们会被擦除)。
84
+ - 重载解析、映射类型、条件类型与模板字面量类型。
85
+ - `node_modules` 下被打包的源码完全不检查:检查器是针对你写的代码的门禁,
86
+ 因为依赖内部而失败会让默认开启的检查器无法与 npm 包共存。
87
+
88
+ ## 关闭检查后的行为
89
+
90
+ `--no-check` 恢复旧的宽松流水线:类型语法被擦除后继续生成代码。它也会恢复
91
+ 静默的 `Duplicate identifier` 行为(`let value = 1; let value = 2;` 可以编译,
92
+ 第一个值生效)。建议保持检查开启。
93
+
94
+ ## 缓存与诊断
95
+
96
+ `check` 是增量缓存 key 的一部分,因此 `--no-check` 的构建产物不会与已检查的
97
+ 产物互相复用。检查开启时,代码生成不再重复报告自己的 `Cannot find name`,
98
+ 每个名字只报一次。`xbintsc check` 会运行检查并在链接前停止,是编辑器和
99
+ pre-commit 钩子的快速门禁。
@@ -9,11 +9,17 @@
9
9
  ```
10
10
  xbintsc build <file.ts> [options] 编译为原生二进制
11
11
  xbintsc run <file.ts> [-- args] 编译并执行
12
+ xbintsc check <file.ts> 解析、绑定并检查,不链接
13
+ xbintsc watch <file.ts> 源码树变化时重新构建
12
14
  xbintsc emit <file.ts> 打印 LLVM IR
15
+ xbintsc doctor 报告解析到的工具链
13
16
  xbintsc version 打印版本
14
17
  xbintsc help 帮助
15
18
  ```
16
19
 
20
+ `check`、`emit`、`build`、`run` 与 `watch` 默认都会运行语义检查;
21
+ `--no-check` 可跳过(该开关也进入缓存 key)。详见[语义检查](./checker.md)。
22
+
17
23
  ## CLI 选项
18
24
 
19
25
  ```
@@ -31,6 +37,9 @@ xbintsc help 帮助
31
37
  --app-id <id> macOS bundle 标识符(如 com.example.demo)
32
38
  --force 忽略增量缓存
33
39
  --verbose 打印进度信息
40
+ --debug 生成 DWARF/CodeView 调试信息
41
+ --check 运行语义检查(默认)
42
+ --no-check 跳过语义检查
34
43
  ```
35
44
 
36
45
  ## 编程接口
@@ -38,8 +47,10 @@ xbintsc help 帮助
38
47
  ```ts
39
48
  import { build, compileString } from "xbintsc";
40
49
 
41
- const { ir } = compileString("console.log(1 + 1);");
50
+ const { ir, diagnostics } = compileString("console.log(1 + 1);");
42
51
  const result = build("program.ts", { emit: "exe", outDir: "build" });
52
+ // 检查器可以按调用关闭,等价于 `--no-check`:
53
+ build("program.ts", { check: false });
43
54
  ```
44
55
 
45
56
  选项与结果类型(`BuildOptions`、`BuildResult`、`EmitKind`、`PhaseTiming`)位于
@@ -23,8 +23,9 @@
23
23
  - 可选链 `?.` / `?.[]` / `?.()`:以空值判断短路到 `undefined`
24
24
  - `delete`、`in`、`instanceof`
25
25
  - `this`(保存到函数 `%saved.this`;箭头函数从环境槽读)、`super`(`super.x` / `super(...)`)、`new`、`await`
26
- - 闭包(箭头函数 / 函数表达式)与捕获环境构建
27
- - 类:构造器闭包 + 原型对象,存入 LLVM 全局(`@class.<id>`);实例字段在构造器体前初始化;`static` 成员存于构造器属性包;`extends` 设置原型链;`super(...)` 通过原型上的隐藏 `__ctor` 调用。
26
+ - 解构:绑定模式中的默认值(`const { a = f() } = o`)按分支生成,`f()` 只在属性为 `undefined` 时求值,绝不会提前执行
27
+ - 闭包(箭头函数 / 函数表达式 / 函数声明)与捕获环境构建:捕获的是符号的**盒子**,因此闭包内的写入会作用到外层绑定。按名调用的函数声明会在调用点构建环境(`fn.captures` / `fn.capturesThis` 为真时不再走直接调用快路径),否则它会以空环境运行,把所有自由变量都读成 `undefined`。
28
+ - 类:构造器闭包 + 原型对象,存入 LLVM 全局(`@class.<id>`);实例字段在构造器体前初始化;`static` 成员存于构造器属性包;`extends` 设置原型链;`super(...)` 通过**父类**原型上的隐藏 `__ctor` 调用。父类由当前定义的类决定(`getPrototype(getPrototype(@class.N))`),绝不由接收者推导:子类实例调用基类构造器时,沿着 `this` 走会解析到错的类,导致超过两层的继承链无限递归。
28
29
  - `async` / `async function*`:闭包分别用 `xt_function_set_async` / `xt_function_set_async_generator` 标记,并在栈式协程上运行——见[异步、Promise 与生成器](./async.md)。
29
30
  - 标准库调用统一走 `xt_call_method` / `xt_math_call` / `xt_object_*` 与各构造器的 `xt_*` 入口;完整表面见[标准库](./stdlib.md)。
30
31
  - 全局字符串池(`@.str.N` 私有常量,UTF-8 转义)。
@@ -7,8 +7,8 @@
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
- - 编译流水线:读源 → 模块打包(`src/driver/modules.ts`,当入口含 `import`/`export` 时)→ 解析 → 绑定/检查 → IR → 目标文件 → 链接。
11
- - 增量缓存:以「编译器版本 + 源码哈希 + emit 类型 + 优化级别 + LTO/PGO 模式 + 平台 + 扩展指纹(名称、链接参数、原生对象内容)」为键,产物存在且新鲜则跳过构建。`--pgo-use` 总是重新构建,因为 profile 数据可能变化而源码不变。缓存键在 `src/driver/build-key.ts` 中组装。
10
+ - 编译流水线:读源 → 模块打包(`src/driver/modules.ts`,当入口含 `import`/`export` 时)→ 解析 → 绑定 → [语义检查](./checker.md) → IR → 目标文件 → 链接。
11
+ - 增量缓存:以「编译器版本 + 源码哈希 + emit 类型 + 优化级别 + LTO/PGO 模式 + 平台 + `check`/`no-check` + 扩展指纹(名称、链接参数、原生对象内容)」为键,产物存在且新鲜则跳过构建。`--pgo-use` 总是重新构建,因为 profile 数据可能变化而源码不变。缓存键在 `src/driver/build-key.ts` 中组装。
12
12
  - C 运行时与扩展源按内容哈希缓存目标文件,只编译一次(缓存键包含 LTO/PGO 参数)。核心翻译单元列表 `RUNTIME_SOURCES` 位于 `src/driver/runtime-objects.ts`。
13
13
  - 工具链封装:查找 `clang`(可用 `xbintsc_CLANG` 覆盖)、编译 IR、编译 C、链接。
14
14
  - LTO(`--lto` / `"lto": true`):程序与运行时都编译为 LLVM bitcode(`-flto`),并用 `-fuse-ld=lld` 链接;需要 lld。