xbintsc 0.5.23 → 0.5.32

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 (481) hide show
  1. package/AGENTS.md +11 -2
  2. package/README.md +47 -16
  3. package/README.zh-CN.md +21 -2
  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 +99 -4
  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 +2 -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 +3 -0
  93. package/dist/src/codegen/generator/module.js +116 -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 +26 -7
  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 +3 -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/gui/css.d.ts +26 -0
  122. package/dist/src/extensions/gui/css.js +100 -0
  123. package/dist/src/extensions/gui/css.js.map +1 -0
  124. package/dist/src/extensions/gui/html.js +28 -7
  125. package/dist/src/extensions/gui/html.js.map +1 -1
  126. package/dist/src/extensions/gui/index.js +79 -2
  127. package/dist/src/extensions/gui/index.js.map +1 -1
  128. package/dist/src/extensions/gui/three.d.ts +16 -0
  129. package/dist/src/extensions/gui/three.js +22 -0
  130. package/dist/src/extensions/gui/three.js.map +1 -0
  131. package/dist/src/extensions/media/index.d.ts +6 -5
  132. package/dist/src/extensions/media/index.js +12 -14
  133. package/dist/src/extensions/media/index.js.map +1 -1
  134. package/dist/src/extensions/registry.d.ts +38 -0
  135. package/dist/src/extensions/registry.js +10 -0
  136. package/dist/src/extensions/registry.js.map +1 -1
  137. package/dist/src/index.d.ts +1 -0
  138. package/dist/src/index.js +1 -0
  139. package/dist/src/index.js.map +1 -1
  140. package/dist/src/parser/declarations/classes.js +7 -0
  141. package/dist/src/parser/declarations/classes.js.map +1 -1
  142. package/dist/src/parser/expressions.js +14 -1
  143. package/dist/src/parser/expressions.js.map +1 -1
  144. package/dist/src/parser/literals.js +6 -2
  145. package/dist/src/parser/literals.js.map +1 -1
  146. package/dist/tests/binder/binder.test.js +29 -0
  147. package/dist/tests/binder/binder.test.js.map +1 -1
  148. package/dist/tests/canonical.test.d.ts +1 -0
  149. package/dist/tests/canonical.test.js +19 -0
  150. package/dist/tests/canonical.test.js.map +1 -0
  151. package/dist/tests/checker/checker.test.d.ts +1 -0
  152. package/dist/tests/checker/checker.test.js +245 -0
  153. package/dist/tests/checker/checker.test.js.map +1 -0
  154. package/dist/tests/cli/check.test.js +20 -0
  155. package/dist/tests/cli/check.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 +45 -0
  170. package/dist/tests/e2e/compile-builtins.test.js.map +1 -1
  171. package/dist/tests/e2e/compile-objects-classes.test.js +77 -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-effects.test.d.ts +6 -0
  182. package/dist/tests/e2e/gui-effects.test.js +262 -0
  183. package/dist/tests/e2e/gui-effects.test.js.map +1 -0
  184. package/dist/tests/e2e/gui-example-browser.test.js +2 -2
  185. package/dist/tests/e2e/gui-example-browser.test.js.map +1 -1
  186. package/dist/tests/e2e/gui-example-canvas.test.js +5 -4
  187. package/dist/tests/e2e/gui-example-canvas.test.js.map +1 -1
  188. package/dist/tests/e2e/gui-example-svg.test.js +4 -3
  189. package/dist/tests/e2e/gui-example-svg.test.js.map +1 -1
  190. package/dist/tests/e2e/gui-example-webgl.test.d.ts +10 -0
  191. package/dist/tests/e2e/gui-example-webgl.test.js +75 -0
  192. package/dist/tests/e2e/gui-example-webgl.test.js.map +1 -0
  193. package/dist/tests/e2e/gui-example-webgl2.test.d.ts +8 -0
  194. package/dist/tests/e2e/gui-example-webgl2.test.js +72 -0
  195. package/dist/tests/e2e/gui-example-webgl2.test.js.map +1 -0
  196. package/dist/tests/e2e/gui-example.test.js +4 -3
  197. package/dist/tests/e2e/gui-example.test.js.map +1 -1
  198. package/dist/tests/e2e/gui-helpers.js +4 -3
  199. package/dist/tests/e2e/gui-helpers.js.map +1 -1
  200. package/dist/tests/e2e/gui-layout.test.js +48 -0
  201. package/dist/tests/e2e/gui-layout.test.js.map +1 -1
  202. package/dist/tests/e2e/gui-media.test.js +10 -8
  203. package/dist/tests/e2e/gui-media.test.js.map +1 -1
  204. package/dist/tests/e2e/gui-webgl.test.d.ts +11 -0
  205. package/dist/tests/e2e/gui-webgl.test.js +179 -0
  206. package/dist/tests/e2e/gui-webgl.test.js.map +1 -0
  207. package/dist/tests/e2e/gui-webgl2.test.d.ts +10 -0
  208. package/dist/tests/e2e/gui-webgl2.test.js +238 -0
  209. package/dist/tests/e2e/gui-webgl2.test.js.map +1 -0
  210. package/dist/tests/e2e/harness.d.ts +9 -0
  211. package/dist/tests/e2e/harness.js +14 -2
  212. package/dist/tests/e2e/harness.js.map +1 -1
  213. package/dist/tests/e2e/native-extensions.test.js +2 -1
  214. package/dist/tests/e2e/native-extensions.test.js.map +1 -1
  215. package/dist/tests/e2e/property-descriptors.test.js +20 -0
  216. package/dist/tests/e2e/property-descriptors.test.js.map +1 -1
  217. package/dist/tests/e2e/unicode-output.test.js +5 -3
  218. package/dist/tests/e2e/unicode-output.test.js.map +1 -1
  219. package/dist/tests/e2e/weak-collections.test.js +16 -2
  220. package/dist/tests/e2e/weak-collections.test.js.map +1 -1
  221. package/dist/tests/extensions/gui.test.js +41 -0
  222. package/dist/tests/extensions/gui.test.js.map +1 -1
  223. package/dist/tests/extensions/media.test.js +7 -3
  224. package/dist/tests/extensions/media.test.js.map +1 -1
  225. package/dist/tests/helpers.d.ts +1 -0
  226. package/dist/tests/helpers.js +1 -0
  227. package/dist/tests/helpers.js.map +1 -1
  228. package/dist/tests/parser/declarations.test.js +20 -0
  229. package/dist/tests/parser/declarations.test.js.map +1 -1
  230. package/dist/tests/parser/expressions.test.js +36 -0
  231. package/dist/tests/parser/expressions.test.js.map +1 -1
  232. package/dist/tests/platform.d.ts +32 -0
  233. package/dist/tests/platform.js +40 -0
  234. package/dist/tests/platform.js.map +1 -0
  235. package/dist/tests/platform.test.d.ts +12 -0
  236. package/dist/tests/platform.test.js +51 -0
  237. package/dist/tests/platform.test.js.map +1 -0
  238. package/dist/tests/version.test.js +4 -4
  239. package/dist/tests/version.test.js.map +1 -1
  240. package/doc/ai/README.md +10 -4
  241. package/doc/ai/build-recipe.md +1 -0
  242. package/doc/ai/cli.md +17 -5
  243. package/doc/ai/contributing.md +59 -2
  244. package/doc/ai/extensions.md +38 -7
  245. package/doc/ai/language-support.md +25 -16
  246. package/doc/ai/troubleshooting.md +12 -8
  247. package/doc/ai/zh-CN/README.md +9 -4
  248. package/doc/ai/zh-CN/build-recipe.md +1 -0
  249. package/doc/ai/zh-CN/cli.md +13 -3
  250. package/doc/ai/zh-CN/contributing.md +49 -3
  251. package/doc/ai/zh-CN/extensions.md +33 -6
  252. package/doc/ai/zh-CN/language-support.md +23 -14
  253. package/doc/ai/zh-CN/troubleshooting.md +10 -6
  254. package/doc/gui/api.md +47 -1
  255. package/doc/gui/build.md +72 -16
  256. package/doc/gui/canvas.md +11 -3
  257. package/doc/gui/dom.md +33 -18
  258. package/doc/gui/known-issues.md +58 -15
  259. package/doc/gui/layout.md +18 -0
  260. package/doc/gui/media.md +17 -13
  261. package/doc/gui/rendering.md +50 -3
  262. package/doc/gui/runtime.md +18 -0
  263. package/doc/gui/webgl.md +256 -0
  264. package/doc/gui-scripts.md +7 -0
  265. package/doc/gui.md +108 -17
  266. package/doc/implemented/binder.md +2 -0
  267. package/doc/implemented/checker.md +117 -0
  268. package/doc/implemented/cli.md +13 -1
  269. package/doc/implemented/codegen.md +3 -2
  270. package/doc/implemented/driver.md +2 -2
  271. package/doc/implemented/operators.md +2 -1
  272. package/doc/implemented/parser.md +3 -2
  273. package/doc/implemented/pipeline.md +8 -1
  274. package/doc/implemented/stdlib.md +2 -1
  275. package/doc/implemented/tests.md +3 -1
  276. package/doc/implemented.md +2 -0
  277. package/doc/npm-package.md +419 -0
  278. package/doc/requirements.md +22 -10
  279. package/doc/support-matrix.md +83 -0
  280. package/doc/unimplemented/classes.md +3 -0
  281. package/doc/unimplemented/deviations.md +3 -2
  282. package/doc/unimplemented/toolchain.md +1 -1
  283. package/doc/unimplemented/types.md +24 -8
  284. package/doc/unimplemented.md +1 -1
  285. package/doc/zh-CN/gui/api.md +43 -1
  286. package/doc/zh-CN/gui/build.md +64 -15
  287. package/doc/zh-CN/gui/canvas.md +9 -2
  288. package/doc/zh-CN/gui/dom.md +20 -7
  289. package/doc/zh-CN/gui/known-issues.md +46 -13
  290. package/doc/zh-CN/gui/layout.md +14 -0
  291. package/doc/zh-CN/gui/media.md +15 -11
  292. package/doc/zh-CN/gui/rendering.md +41 -4
  293. package/doc/zh-CN/gui/runtime.md +16 -0
  294. package/doc/zh-CN/gui/webgl.md +115 -0
  295. package/doc/zh-CN/gui-scripts.md +5 -0
  296. package/doc/zh-CN/gui.md +89 -14
  297. package/doc/zh-CN/implemented/binder.md +2 -0
  298. package/doc/zh-CN/implemented/checker.md +99 -0
  299. package/doc/zh-CN/implemented/cli.md +12 -1
  300. package/doc/zh-CN/implemented/codegen.md +3 -2
  301. package/doc/zh-CN/implemented/driver.md +2 -2
  302. package/doc/zh-CN/implemented/operators.md +1 -1
  303. package/doc/zh-CN/implemented/parser.md +3 -2
  304. package/doc/zh-CN/implemented/pipeline.md +3 -1
  305. package/doc/zh-CN/implemented/stdlib.md +2 -1
  306. package/doc/zh-CN/implemented/tests.md +3 -1
  307. package/doc/zh-CN/implemented.md +2 -0
  308. package/doc/zh-CN/npm-package.md +394 -0
  309. package/doc/zh-CN/post/announce.md +47 -47
  310. package/doc/zh-CN/requirements.md +16 -7
  311. package/doc/zh-CN/support-matrix.md +82 -0
  312. package/doc/zh-CN/unimplemented/classes.md +3 -0
  313. package/doc/zh-CN/unimplemented/deviations.md +3 -2
  314. package/doc/zh-CN/unimplemented/toolchain.md +1 -1
  315. package/doc/zh-CN/unimplemented/types.md +16 -6
  316. package/doc/zh-CN/unimplemented.md +1 -1
  317. package/llms.txt +6 -1
  318. package/package.json +2 -1
  319. package/runtime/ext_gui/audio.cpp +316 -0
  320. package/runtime/ext_gui/browser.cpp +573 -0
  321. package/runtime/ext_gui/browser_escape.cpp +85 -0
  322. package/runtime/ext_gui/browser_loop.cpp +83 -0
  323. package/runtime/ext_gui/canvas.cpp +12 -21
  324. package/runtime/ext_gui/canvas_internal.h +10 -0
  325. package/runtime/ext_gui/canvas_raster.cpp +79 -1
  326. package/runtime/ext_gui/clip_values.cpp +246 -0
  327. package/runtime/ext_gui/css.cpp +94 -0
  328. package/runtime/ext_gui/css.h +22 -1
  329. package/runtime/ext_gui/css_match.cpp +3 -0
  330. package/runtime/ext_gui/css_selector.cpp +9 -0
  331. package/runtime/ext_gui/css_sheet.cpp +89 -45
  332. package/runtime/ext_gui/document.cpp +4 -1
  333. package/runtime/ext_gui/document.h +2 -0
  334. package/runtime/ext_gui/dom.h +16 -0
  335. package/runtime/ext_gui/dom_api.cpp +37 -0
  336. package/runtime/ext_gui/dom_api_canvas.cpp +17 -80
  337. package/runtime/ext_gui/dom_api_canvas_extra.cpp +130 -1
  338. package/runtime/ext_gui/dom_api_canvas_pending.cpp +41 -0
  339. package/runtime/ext_gui/dom_api_document.cpp +96 -5
  340. package/runtime/ext_gui/dom_api_events.cpp +20 -0
  341. package/runtime/ext_gui/dom_api_internal.h +278 -0
  342. package/runtime/ext_gui/dom_api_proto.cpp +6 -0
  343. package/runtime/ext_gui/dom_api_webgl.cpp +376 -0
  344. package/runtime/ext_gui/dom_api_webgl2.cpp +434 -0
  345. package/runtime/ext_gui/dom_api_webgl2_draw.cpp +269 -0
  346. package/runtime/ext_gui/dom_api_webgl_buffer.cpp +212 -0
  347. package/runtime/ext_gui/dom_api_webgl_rt.h +30 -0
  348. package/runtime/ext_gui/dom_api_webgl_shader.cpp +443 -0
  349. package/runtime/ext_gui/dom_api_webgl_state.cpp +444 -0
  350. package/runtime/ext_gui/dom_api_webgl_texture.cpp +445 -0
  351. package/runtime/ext_gui/effect_values.cpp +312 -0
  352. package/runtime/ext_gui/gradient_values.cpp +476 -0
  353. package/runtime/ext_gui/grid_values.cpp +230 -0
  354. package/runtime/ext_gui/gui.cpp +90 -23
  355. package/runtime/ext_gui/gui_canvas.cpp +50 -2
  356. package/runtime/ext_gui/gui_engine.h +71 -0
  357. package/runtime/ext_gui/gui_events.cpp +4 -1
  358. package/runtime/ext_gui/gui_media.cpp +1 -1
  359. package/runtime/ext_gui/gui_webgl.cpp +83 -0
  360. package/runtime/ext_gui/layout.cpp +21 -0
  361. package/runtime/ext_gui/layout_flow.cpp +81 -4
  362. package/runtime/ext_gui/layout_flow_internal.h +31 -0
  363. package/runtime/ext_gui/layout_grid.cpp +374 -0
  364. package/runtime/ext_gui/media.h +1 -1
  365. package/runtime/ext_gui/media_api.h +2 -2
  366. package/runtime/ext_gui/media_query.cpp +211 -0
  367. package/runtime/ext_gui/paint.cpp +111 -77
  368. package/runtime/ext_gui/paint.h +33 -3
  369. package/runtime/ext_gui/paint_background.cpp +229 -0
  370. package/runtime/ext_gui/paint_clip.cpp +268 -0
  371. package/runtime/ext_gui/paint_effects.cpp +324 -0
  372. package/runtime/ext_gui/paint_internal.h +85 -0
  373. package/runtime/ext_gui/renderer.cpp +8 -31
  374. package/runtime/ext_gui/renderer_clip.cpp +196 -0
  375. package/runtime/ext_gui/renderer_image.cpp +13 -8
  376. package/runtime/ext_gui/renderer_internal.h +15 -8
  377. package/runtime/ext_gui/renderer_text.cpp +6 -31
  378. package/runtime/ext_gui/style.cpp +343 -20
  379. package/runtime/ext_gui/style.h +144 -3
  380. package/runtime/ext_gui/style_print.cpp +134 -1
  381. package/runtime/ext_gui/style_values.cpp +152 -126
  382. package/runtime/ext_gui/style_values_internal.h +35 -0
  383. package/runtime/ext_gui/webgl.h +466 -0
  384. package/runtime/ext_gui/webgl2_constants.h +274 -0
  385. package/runtime/ext_gui/webgl_buffer.cpp +565 -0
  386. package/runtime/ext_gui/webgl_constants.h +317 -0
  387. package/runtime/ext_gui/webgl_context.cpp +466 -0
  388. package/runtime/ext_gui/webgl_draw.cpp +495 -0
  389. package/runtime/ext_gui/webgl_glsl.h +125 -0
  390. package/runtime/ext_gui/webgl_glsl_compile.cpp +431 -0
  391. package/runtime/ext_gui/webgl_glsl_rewrite.cpp +349 -0
  392. package/runtime/ext_gui/webgl_glsl_scan.cpp +581 -0
  393. package/runtime/ext_gui/webgl_msl.cpp +62 -0
  394. package/runtime/ext_gui/webgl_msl.h +33 -0
  395. package/runtime/ext_gui/webgl_pipeline.cpp +274 -0
  396. package/runtime/ext_gui/webgl_program_internal.h +18 -0
  397. package/runtime/ext_gui/webgl_shader.cpp +582 -0
  398. package/runtime/ext_gui/webgl_texture.cpp +293 -0
  399. package/runtime/ext_gui/webgl_uniform.cpp +167 -0
  400. package/runtime/ext_gui/webgl_webgl2.cpp +224 -0
  401. package/runtime/ext_gui/window.cpp +9 -0
  402. package/runtime/ext_media/media.cpp +1 -1
  403. package/runtime/ext_media/media_bridge.c +9 -3
  404. package/runtime/ext_node/path/path.c +7 -7
  405. package/runtime/ext_node/url/url.c +4 -2
  406. package/runtime/rt.h +15 -0
  407. package/runtime/rt_internal.h +1 -0
  408. package/runtime/xt_constructors.c +2 -1
  409. package/runtime/xt_containers/access.inc +8 -0
  410. package/runtime/xt_containers/objects.inc +22 -2
  411. package/runtime/xt_io/exception.inc +4 -2
  412. package/runtime/xt_regex/api.inc +2 -0
  413. package/runtime/xt_regex/matcher.inc +16 -3
  414. package/runtime/xt_regex/parser.inc +8 -2
  415. package/runtime/xt_regex/types.inc +3 -0
  416. package/runtime/xt_stdlib/math.inc +62 -0
  417. package/runtime/xt_stdlib2/date.inc +7 -1
  418. package/runtime/xt_stdlib2/objects.inc +14 -0
  419. package/runtime/xt_stdlib2/regexp-match.inc +60 -21
  420. package/runtime/xt_stdlib2/regexp.inc +1 -0
  421. package/runtime/xt_typed_array.c +1 -1
  422. package/scripts/build-gui.ts +90 -3
  423. package/scripts/build-media.ts +323 -58
  424. package/scripts/setup-vs-toolchain.ps1 +152 -0
  425. package/scripts/support-matrix.ts +167 -0
  426. package/src/ast/common.ts +2 -0
  427. package/src/ast/declarations.ts +12 -1
  428. package/src/ast/expressions.ts +6 -0
  429. package/src/ast/kinds.ts +2 -0
  430. package/src/binder/binder.ts +3 -0
  431. package/src/binder/declarations.ts +70 -0
  432. package/src/binder/references.ts +97 -4
  433. package/src/binder/types.ts +30 -0
  434. package/src/canonical.ts +37 -0
  435. package/src/checker/assignability.ts +134 -0
  436. package/src/checker/calls.ts +135 -0
  437. package/src/checker/checker.ts +47 -0
  438. package/src/checker/declarations.ts +26 -0
  439. package/src/checker/flow.ts +236 -0
  440. package/src/checker/globals.ts +40 -0
  441. package/src/checker/source.ts +53 -0
  442. package/src/checker/type-infer.ts +185 -0
  443. package/src/checker/type-model.ts +212 -0
  444. package/src/checker/type-system.ts +578 -0
  445. package/src/checker/typecheck-types.ts +112 -0
  446. package/src/checker/typecheck.ts +586 -0
  447. package/src/checker/undefined.ts +43 -0
  448. package/src/checker/walk.ts +16 -0
  449. package/src/cli/help.ts +65 -0
  450. package/src/cli/hints.ts +2 -1
  451. package/src/cli/main.ts +12 -49
  452. package/src/codegen/generator/calls/access.ts +8 -8
  453. package/src/codegen/generator/calls/invocation.ts +8 -5
  454. package/src/codegen/generator/calls/super.ts +67 -5
  455. package/src/codegen/generator/context.ts +31 -19
  456. package/src/codegen/generator/debug.ts +2 -1
  457. package/src/codegen/generator/expressions/primary.ts +84 -13
  458. package/src/codegen/generator/generator.ts +11 -1
  459. package/src/codegen/generator/module.ts +115 -24
  460. package/src/codegen/generator/state.ts +11 -1
  461. package/src/codegen/generator/statements/variables.ts +26 -6
  462. package/src/codegen/generator/tables.ts +5 -0
  463. package/src/driver/build-key.ts +3 -0
  464. package/src/driver/bundler/graph.ts +6 -2
  465. package/src/driver/bundler/merge.ts +14 -1
  466. package/src/driver/bundler/types.ts +13 -0
  467. package/src/driver/compiler.ts +4 -1
  468. package/src/driver/fingerprint.ts +2 -1
  469. package/src/driver/frontend.ts +13 -2
  470. package/src/driver/options.ts +6 -0
  471. package/src/driver/version.ts +1 -1
  472. package/src/extensions/gui/css.ts +113 -0
  473. package/src/extensions/gui/html.ts +31 -11
  474. package/src/extensions/gui/index.ts +81 -2
  475. package/src/extensions/gui/three.ts +25 -0
  476. package/src/extensions/media/index.ts +13 -16
  477. package/src/extensions/registry.ts +48 -0
  478. package/src/index.ts +1 -0
  479. package/src/parser/declarations/classes.ts +7 -0
  480. package/src/parser/expressions.ts +13 -1
  481. package/src/parser/literals.ts +6 -2
@@ -10,9 +10,10 @@
10
10
  `DisplayList`:一个按画家顺序排列的 `ops` 列表,包含**矩形**(背景与四条实心
11
11
  边框,带 `border-radius`)、**文本 run**(每个携带其文本、颜色与已解析的
12
12
  `FontSpec`)与**图像**,背后由并列的负载数组支撑。每个 op 还携带当前生效的裁剪
13
- 矩形(最近的 `overflow: hidden` 祖先的 padding box),因此 `overflow` 裁剪与
14
- `z-index` 顺序都能保留到渲染器。`DisplayList::dump()` 为
15
- `paintList()`/`paintCount()` 提供数据。
13
+ 矩形(最近的 `overflow: hidden` 祖先的 padding box)以及最多两个指向显示列表
14
+ 三角化 `clip-path` 多边形的下标,因此 `overflow`/`clip-path` 裁剪与 `z-index`
15
+ 顺序都能保留到渲染器。`DisplayList::dump()` 为 `paintList()`/`paintCount()`
16
+ 提供数据。
16
17
 
17
18
  `opacity` 只在两端生效:计算值为 `0` 的盒子(及其整棵子树)不绘制任何内容,
18
19
  大于 `0` 的一律按完全不透明绘制。图形只携带其颜色自身的 alpha,因此没有部分
@@ -61,7 +62,43 @@
61
62
 
62
63
  窗口背景(`setBackground`)是渲染通道的清除色。
63
64
 
64
- M4 仍需完成:渐变。
65
+ ### 背景、生成内容与特效(M19)
66
+
67
+ `background-color` 与每一条 `background-image` 层都会绘制。逗号分隔的层列表按
68
+ 从底到上的顺序绘制(声明中的第一层在最上面),两种渐变均受支持:
69
+
70
+ - **线性**渐变在 18 个位置采样并输出为纯色矩形;支持 `to <side>`、
71
+ `deg`/`grad`/`rad`/`turn`、百分比与多色标(色带沿最近轴行走,因此斜角会退化为
72
+ 最近的轴向);
73
+ - **径向**渐变是 32 个同心椭圆。每个都是单位半径的圆角矩形,经图形管线的
74
+ transform 槽映射,因此圆/椭圆仍保留距离场抗锯齿。支持形状/尺寸关键字
75
+ (`circle`/`ellipse`、`closest-side`/`farthest-side`/`closest-corner`/
76
+ `farthest-corner`、显式半径)与 `at <position>`。
77
+
78
+ 背景色位于所有层下方。若渐变色标带透明度,渐变也会半透明;色带近似可能产生
79
+ 轻微条带,非常透明的多色标渐变会出现 alpha 叠加。
80
+
81
+ **生成内容**不需要新的显示列表类型:`::before`/`::after` 是 `style.cpp` 中
82
+ 每次重算样式时重建的普通布局盒,因此其背景、边框、文本与 transform 都走同一条
83
+ 绘制路径。`content` 支持字符串、`attr()` 与 open/close quote。
84
+
85
+ **`text-shadow`** 会作为阴影 `PaintText` run 排在真实 run 之前,因此文本管线
86
+ 无需新 shader 就能绘制。带模糊的阴影是围绕偏移量展开的九个半透明副本(与
87
+ `filter: blur()` 相同的近似)。
88
+
89
+ **`clip-path`** 在 `paint_clip.cpp` 中解析为设备空间多边形(每个点都应用盒子的
90
+ transform),用耳切法三角化,并存入 `DisplayList::clip_paths`。每个 op 的
91
+ `PaintClip` 最多携带两个路径下标;`renderer_clip.cpp` 在上传时把每个凸的图形/
92
+ 字形/图像四边形与这些三角形求交。即使 `polygon()` 是凹多边形也正确,无需模板或
93
+ shader 改动,但边缘是硬边(没有解析抗锯齿)。支持两层嵌套路径求交;更深时保留
94
+ 最外两层。
95
+
96
+ **`filter`** 的颜色函数(`brightness`、`contrast`、`grayscale`、`sepia`、
97
+ `invert`、`saturate`、`hue-rotate`、`opacity`)会折进每个绘制颜色,因此盒子与
98
+ 其后代都会看到滤镜。`blur()` 与 `drop-shadow()` 是显示列表层面的近似:模糊把每个
99
+ 图形展开成九个半透明副本,投影用盒子/文字轮廓。这样保持单渲染通道(没有离屏
100
+ 渲染目标),代价是组语义:被模糊/滤镜的组内重叠后代可能加深;`backdrop-filter`
101
+ 无法采样元素背后的内容,因此会解析并参与层叠,但不绘制。
65
102
 
66
103
  ## 文本技术栈(M4b)
67
104
 
@@ -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 桥接
@@ -0,0 +1,115 @@
1
+ # WebGL(由 GPU 绘制的 `<canvas>`)
2
+
3
+ > 语言 / Language:[English](../../gui/webgl.md) | **简体中文**
4
+
5
+ > 属于 [GUI 扩展](../gui.md);引擎总览、已定决策与路线图都在那里。
6
+
7
+ `<canvas>` 可以申请 WebGL 上下文,而不是 2D 上下文:
8
+
9
+ ```ts
10
+ const canvas: any = document.getElementById("scene");
11
+ const gl: any = canvas.getContext("webgl2"); // 或 "webgl" / "experimental-webgl"
12
+ if (gl == null) {
13
+ // 该平台的 GPU 后端无法消费 WebGL 的着色器
14
+ }
15
+ ```
16
+
17
+ 2D 上下文把图形光栅化到 CPU 位图再上传为纹理;WebGL 上下文则**在 GPU 上渲染**:顶点变换、光照、纹理采样、深度测试与混合全部在 SDL_GPU 管线中执行(Windows/Linux 上是 Vulkan,macOS 上是 Metal)。页面直接合成该上下文的颜色纹理,因此显示时不需要把像素读回 CPU。
18
+
19
+ 同时提供 **WebGL 1.0** 与 **WebGL 2.0**。一个 canvas 会固定为它第一次申请的上下文类型:先调用 `getContext("webgl2")` 之后,`getContext("webgl")` 返回 `null`,反之亦然。WebGL 2 上下文也满足 `instanceof WebGLRenderingContext`(其原型继承 WebGL 1 原型),并在其上增加 WebGL 2 的常量与方法。
20
+
21
+ ## 一帧如何到达屏幕
22
+
23
+ - 每个上下文拥有一张离屏 `R8G8B8A8_UNORM` 颜色纹理(绘图缓冲)和一张 `D32_FLOAT` 深度纹理,尺寸取自 canvas 的 `width` / `height` 属性。`canvas.width = …` 会重建它们并丢弃内容,与 DOM 规则一致。
24
+ - 上下文记录到自己的 SDL_GPU 命令缓冲。`clear`/`draw*` 保持一个渲染 pass 打开;缓冲区/纹理上传或切换 framebuffer 会结束它,并以 `LOAD` 开始新 pass,因此绘图缓冲在多次绘制之间保留,和 WebGL 一样。
25
+ - 每帧一次,在页面自己的渲染 pass 之前,引擎提交所有 WebGL 命令缓冲。随后图像管线把颜色纹理当作普通 `PaintImage` 采样,没有 CPU 拷贝。
26
+ - WebGL 原点在左下,SDL_GPU 渲染目标原点在左上,因此帧缓冲按自上而下存储:转换 `viewport`/`scissor`,`readPixels` 再把行翻回去,合成器看到的是正立的纹理。
27
+ - 固定功能状态变化(`blendFunc`、`depthFunc`、`cullFace`、`colorMask` 等)会改变所需的 `SDL_GPUGraphicsPipeline`,因此管线按(程序、顶点布局、状态)惰性创建,并缓存在程序上。
28
+
29
+ ## 着色器:GLSL ES 到 SPIR-V(再到 MSL)
30
+
31
+ SDL_GPU 不能在运行时编译 GLSL,且每个后端只消费自己的格式,因此引擎静态链接了两个翻译器:
32
+
33
+ - **glslang** 把改写后的 GLSL 编译为 SPIR-V,Vulkan 后端直接消费;
34
+ - **SPIRV-Cross** 把同一份 SPIR-V 交叉编译为 Metal Shading Language 文本,Metal 后端在运行时编译它。
35
+
36
+ 两者都打进 `gui.a` / `gui.lib`;Metal 路径复用 SPIR-V 模块而不是再写一套 GLSL 前端,因此两个后端接受完全相同的着色器子集。流程是:
37
+
38
+ 1. `shaderSource` 保存 GLSL ES 文本;`compileShader` 先翻译一次,供 `COMPILE_STATUS` / `getShaderInfoLog` 使用。
39
+ 2. `linkProgram` 用共享的属性/`varying` 位置表再翻译两个阶段,用 glslang 编译,然后创建 `SDL_GPUShader`:Vulkan 上直接用 SPIR-V,Metal 上用 SPIRV-Cross 产出的 MSL 文本。
40
+ 3. 反射生成的 SPIR-V,取得 uniform 块精确的 std140 偏移、数组步长与矩阵步长——源码里数组长度可以写宏,glslang 已经解析好了。SPIRV-Cross 会在 MSL 结构体中保留这些偏移,因此一份 uniform 布局同时服务两个后端。
41
+
42
+ 翻译器(`runtime/ext_gui/webgl_glsl*.cpp`)处理 GLSL ES 1.00 与 3.00:
43
+
44
+ | WebGL 写法 | 改写为 |
45
+ | --- | --- |
46
+ | `attribute vec3 a_pos` | `layout(location = N) in vec3 a_pos` |
47
+ | `varying vec2 v_uv` | `layout(location = N) out/in vec2 v_uv`(共享的名字 → 位置表) |
48
+ | `gl_FragColor` | `layout(location = 0) out highp vec4 xt_FragColor` |
49
+ | `texture2D`、`textureCube`、`texture2DProj` | `texture`、`texture`、`textureProj` |
50
+ | `texture2DLodEXT` / `textureCubeLodEXT` | `textureLod` |
51
+ | 非采样器 uniform | 一个 `layout(std140) uniform XtUniforms { … }` 块 |
52
+ | `uniform sampler2D u_tex` | `layout(set = 2, binding = N) uniform sampler2D u_tex`(片元)或 set 0(顶点) |
53
+ | `gl_FragData[0]` | `xt_FragColor` |
54
+ | 缺少 `#version` / `#version 100` | `#version 310 es` |
55
+
56
+ 两个阶段的非采样器 uniform 会合并成同一个块,并在每个阶段各声明一次(顶点 set 1、片元 set 3),与 SDL_GPU 的 Vulkan 描述符布局一致。在 Metal 上同一批声明会变成 `[[buffer(0)]]` 与 `[[texture(N)]]`/`[[sampler(N)]]`,正是 SDL_GPU Metal 后端绑定的槽位。`uniformMatrix4fv` 按列主序写入反射出的偏移;对采样器调用 `uniform1i` 时记录纹理单元。每次绘制都用动态 uniform 缓冲接口推送该块。
57
+
58
+ 翻译器的限制:结构体 uniform、用户 uniform 块、预处理后仍无法确定长度的 uniform 数组、采样器数组与立方体贴图都会被拒绝(着色器/链接日志会说明)。`#ifdef` 内的代码没问题;非采样器 uniform 声明会被移到外层顶层位置,保证块是无条件的。
59
+
60
+ ### GLSL ES 3.00(WebGL 2)
61
+
62
+ `#version 300 es` 源码除版本号提升外会被原样接受:顶层 `in`/`out` 声明会变成属性/`varying`,命名片元输出(`out vec4 fragColor;`)会变成 `xt_FragColor` 形式的输出,`texture()` / `textureLod()` 本就与 Vulkan 方言一致。多个片元输出会分配连续 location,但渲染 pass 只有一个颜色目标,因此只写入第一个。GLSL ES 3.00 提供 `gl_VertexID` 与 `gl_InstanceID`,实例化示例正是用它。
63
+
64
+ ## 支持的 API
65
+
66
+ - **上下文**:`getContext("webgl")`、`canvas`、`drawingBufferWidth/Height`、`getParameter`、`getError`、`getSupportedExtensions`、`getExtension`、`getContextAttributes`、`isContextLost`、`getShaderPrecisionFormat`,以及模板入口(接受状态;深度目标没有模板附件)。
67
+ - **着色器与程序**:`createShader`、`shaderSource`、`compileShader`、`getShaderParameter`、`getShaderInfoLog`、`getShaderSource`、`deleteShader`、`createProgram`、`attachShader`、`detachShader`、`linkProgram`、`getProgramParameter`、`getProgramInfoLog`、`getAttachedShaders`、`validateProgram`、`deleteProgram`、`useProgram`、`getActiveUniform`/`getActiveAttrib`、`getUniformLocation`、`getAttribLocation`、`bindAttribLocation`。
68
+ - **Uniform**:`uniform1f`…`uniform4f`、`uniform1i`…`uniform4i`、`uniform1fv`…`uniform4fv`、`uniform1iv`…`uniform4iv`、`uniformMatrix2fv`/`3fv`/`4fv`、`getUniform`。
69
+ - **缓冲与顶点属性**:`createBuffer`、`bindBuffer`、`bufferData`、`bufferSubData`、`deleteBuffer`、`getBufferParameter`、`enableVertexAttribArray`、`disableVertexAttribArray`、`vertexAttribPointer`、`vertexAttrib1f`…`4f` / `1fv`…`4fv`、`getVertexAttrib`。
70
+ - **绘制**:`drawArrays`、`drawElements`(UNSIGNED_BYTE、UNSIGNED_SHORT、UNSIGNED_INT;`TRIANGLE_FAN` 与 `LINE_LOOP` 会展开为列表)。`POINTS`、`LINES`、`LINE_STRIP`、`TRIANGLES`、`TRIANGLE_STRIP` 映射到对应的 SDL 图元。
71
+ - **纹理**:`createTexture`、`bindTexture`、`activeTexture`、`texParameteri`/`texParameterf`、`getTexParameter`、`texImage2D`(原始像素、`<img>`、`<canvas>`、`ImageData`)、`texSubImage2D`、`generateMipmap`、`deleteTexture`。支持 `UNPACK_FLIP_Y_WEBGL` 与 `UNPACK_PREMULTIPLY_ALPHA_WEBGL`。全部转换为 RGBA8;接受 `RGBA`、`RGB`、`LUMINANCE`、`ALPHA`、`LUMINANCE_ALPHA` 配 `UNSIGNED_BYTE`。
72
+ - **Framebuffer**:`createFramebuffer`、`bindFramebuffer`、`framebufferTexture2D`(颜色附件)、`checkFramebufferStatus`、`createRenderbuffer`、`bindRenderbuffer`、`renderbufferStorage`(深度)、`framebufferRenderbuffer`、`delete*`。足以实现渲染到纹理、阴影贴图与后处理。
73
+ - **状态**:`enable`/`disable`/`isEnabled`(`BLEND`、`DEPTH_TEST`、`CULL_FACE`、`SCISSOR_TEST`;模板状态接受但不生效)、`clearColor`/`clearDepth`/`clearStencil`、`clear`、`blendFunc`/`blendFuncSeparate`、`blendEquation`/`blendEquationSeparate`、`depthFunc`、`depthMask`、`colorMask`、`cullFace`、`frontFace`、`viewport`、`scissor`、`pixelStorei`、`finish`。
74
+ - **读回**:`readPixels`(RGBA/UNSIGNED_BYTE),可从默认帧缓冲或绑定的 framebuffer 读取。它会阻塞到 GPU 完成;用于测试和截图,不要每帧调用。
75
+
76
+ WebGL 2 额外提供:
77
+
78
+ - **顶点数组对象**:`createVertexArray`、`bindVertexArray`、`deleteVertexArray`、`isVertexArray`。SDL_GPU 没有 VAO,绑定一个会恢复保存下来的属性表及其元素缓冲。
79
+ - **实例化**:`drawArraysInstanced`、`drawElementsInstanced`、`drawRangeElements`、`vertexAttribDivisor`。divisor 为 1 映射到 SDL 的按实例输入频率;SDL 3.2 保留更大的步进值,因此大于 1 的 divisor 会被钳制为 1。
80
+ - **整数属性与 uniform**:`vertexAttribIPointer`、`vertexAttribI4*` 系列、`uniform1ui`…`uniform4ui`。
81
+ - **采样器对象**:`createSampler`、`bindSampler`、`deleteSampler`、`samplerParameteri/f`、`getSamplerParameter`;绑定的采样器会覆盖该单元上纹理自身的过滤/环绕状态。
82
+ - **不可变纹理与缓冲拷贝**:`texStorage2D`(后端始终分配完整 mip 链)、`copyBufferSubData`、`getBufferSubData`。
83
+ - **清除**:`clearBufferfv`、`clearBufferiv`、`clearBufferuiv`、`clearBufferfi`。
84
+ - **查询与栅栏**:对象与入口都存在(`createQuery`/`beginQuery`/`endQuery`/`getQueryParameter`、`fenceSync`/`clientWaitSync`/`waitSync`/`getSyncParameter`),行为是优雅降级:栅栏报告 `ALREADY_SIGNALED`,查询结果为 0。
85
+ - **Uniform 块**:`getUniformBlockIndex` 返回 `INVALID_INDEX`,让库回退到独立 uniform;块相关入口为空操作。
86
+ - **Transform feedback、3D 纹理与压缩格式**:入口存在但为空操作,避免特性探测类库抛错。
87
+
88
+ 纹理创建时带完整 mip 链;在 `generateMipmap` 之前采样被钳制到第 0 层。矩阵顶点属性会占用相应数量的连续 location,每个 location 读取一列。未启用的属性由最近一次 `vertexAttrib*f` 的值通过一个小常量缓冲提供。
89
+
90
+ ## 未实现
91
+
92
+ 着色器源码里的 uniform buffer 对象、transform feedback(入口为空操作)、立方体贴图、3D/数组纹理、浮点/半浮点纹理、深度纹理、压缩纹理、多渲染目标(只写第一个片元输出)、`blitFramebuffer`、MSAA/采样缓冲、模板操作(状态接受,但不写模板缓冲)、常量混合颜色、`drawingBufferStorage`、上下文丢失、`bufferData` 的非 static/dynamic `usage`(提示被忽略)、`texImage2D` 对 `HTMLVideoElement`/`ImageBitmap` 的支持,以及带 scissor 的 `clear`(clear 会清空整个附件)。使用内建块、用户 uniform 块或超出支持范围的 `gl_FragDepth` 的着色器会以编译/链接日志报错。
93
+
94
+ 引擎报告的顶点纹理单元数量为 0,因此行为良好的 WebGL 1 程序不会在顶点着色器里采样纹理。
95
+
96
+ ## 平台
97
+
98
+ 管线按 SDL_GPU 设备接受的着色器格式创建:Vulkan 上用 **SPIR-V**(`SDL_GPU_SHADERFORMAT_SPIRV`,Windows/Linux 选择的后端),macOS 上用 **MSL**(`SDL_GPU_SHADERFORMAT_MSL`,Metal 后端)。两个后端共用同一个 GLSL 前端,因此在一个后端能编译的着色器在另一个上也能编译。如果设备的后端两种格式都不接受——Direct3D 12 需要 DXIL——`getContext("webgl")` 与 `getContext("webgl2")` 都会返回 `null`;2D canvas 与页面其余部分仍然正常。
99
+
100
+ `npm run gui` 会拉取并构建 glslang 与 SPIRV-Cross,合并进 `gui.a` / `gui.lib`(见[打包与构建](./build.md));只用 2D canvas 或 DOM 的程序除了归档体积之外没有运行时开销。
101
+
102
+ ## 测试
103
+
104
+ - `tests/e2e/gui-webgl.test.ts` 编译 GLSL、绘制带纹理和深度测试的四边形、检查面剔除,并读回像素。
105
+ - `tests/e2e/gui-webgl2.test.ts` 覆盖 WebGL 2 的新增能力:`#version 300 es` 着色器、VAO 往返、带 divisor 的实例化绘制、`texStorage2D`、`clearBufferfv`、缓冲拷贝、采样器对象与结构体 uniform 字段。
106
+ - `examples/gui/webgl-cube` 是一个旋转、受光、带纹理的立方体;它在浏览器中原样运行,并由 `tests/e2e/gui-example-webgl.test.ts` 覆盖。
107
+ - `examples/gui/webgl2-cubes` 用一次绘制调用画出 64 个实例化立方体,使用 `#version 300 es` 与 VAO;由 `tests/e2e/gui-example-webgl2.test.ts` 覆盖。
108
+
109
+ 这些用例会在宿主选择的后端上运行:Linux(与 Windows)上是 Vulkan,macOS 上是 Metal,因此 SPIRV-Cross → MSL 路径与 SPIR-V 路径受同一组断言保护。
110
+
111
+ ## three.js
112
+
113
+ `.js` 资源加载器现在只修补 three.js 的着色器循环展开;`WebGLRenderer` 在本引擎真正的 WebGL 2 后端上原样运行,**不再打包 Canvas2D 回退**。已用 three.js r160 通过 SDL_GPU 验证:`MeshBasicMaterial`、`MeshStandardMaterial`、`MeshPhongMaterial`、`CanvasTexture`、线性雾、环境光/平行光/点光/聚光/半球光、`Sprite`、`Line`、`Points` 与 `InstancedMesh`。
114
+
115
+ 本引擎子集之外的能力仍无法模拟:阴影贴图(深度纹理)、立方体贴图/环境贴图、HDR/浮点渲染目标、多渲染目标、transform feedback 与压缩纹理。需要这些能力的场景无法正确渲染;此前 Canvas2D 回退能显示的内容现在全部走 GPU。
@@ -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
@@ -2,7 +2,7 @@
2
2
 
3
3
  > 语言 / Language:[English](../gui.md) | **简体中文**
4
4
 
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** 真正播放
5
+ 状态:**M19** —— 功能(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
6
  `<video>`/`<audio>`——可选的 `media` 扩展用 vendored 的最小 FFmpeg 在主线程解码,
7
7
  视频帧走图像纹理路径、音频进入 SDL 流,DOM 媒体 API 暴露
8
8
  `play`/`pause`/`currentTime`/… 与媒体事件。只启用 `gui` 不会链接 FFmpeg。**M14** 增加了 `<canvas>`,配一个自研的 2D 软件光栅器(抗锯齿
@@ -12,7 +12,7 @@
12
12
  渲染器,因此盒子(以及其中的文本、图像与子元素)可以被平移、缩放与旋转而
13
13
  不触发任何重排——再加上 `transition: transform`,这些姿态可以动画(自绘的示例
14
14
  `examples/gui/pelican-svg` 正是用它让矢量画动起来)。参见
15
- [布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)。本总览记录了锁定决策、架构、里程碑计划与当前进度;引擎本身按功能拆分在以上各页中。
15
+ [布局](./gui/layout.md#变换m15)与[动画](./gui/animation.md#css-transformm15)。**M17** 增加了真正的 **WebGL 1.0**,**M18** 增加了 **WebGL 2.0**:`<canvas>.getContext("webgl2")` 接受 `#version 300 es` 着色器、顶点数组对象、实例化绘制与采样器对象,全部由内置 glslang 编译为 SPIR-V(Metal 上再由内置 SPIRV-Cross 转成 MSL)并通过 SDL_GPU 渲染,几何、光照、纹理采样与混合都在 GPU 上完成,页面直接合成颜色纹理而无须读回——见 [WebGL](./gui/webgl.md)。**M19** 补齐 CSS 装饰层:`@media` 查询、生成内容(`::before`/`::after`)、线性/径向多层背景、`text-shadow`、`clip-path` 与 `filter` 颜色/阴影效果。`backdrop-filter` 与真正的组模糊需要离屏合成器,仍为有文档说明的近似或未支持——见[绘制](./gui/rendering.md#背景生成内容与特效m19)。本总览记录了锁定决策、架构、里程碑计划与当前进度;引擎本身按功能拆分在以上各页中。
16
16
 
17
17
  ## 目录
18
18
 
@@ -135,19 +135,24 @@ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
135
135
  - **M6b — transition/动画** ✅ `transition` 简写 + 长写、对
136
136
  `background-color`/`color`/`border-color`/`border-radius` 的动画、重定向
137
137
  与 `win.advance(ms)`。`@keyframes` 仍待完成。
138
- 7. **M7 — CI 与发布** ✅(Linux/macOS 构建) / 🚧(运行 + Windows)
138
+ 7. **M7 — CI 与发布** ✅(Linux/macOS 构建) / 🚧(运行 + Windows arm64)
139
139
  - `compile-examples` 在 Linux 与 macOS 上构建 `gui.a` 与 `media.a`(必需),
140
140
  然后在 Linux 上的 Xvfb + lavapipe 下运行示例与 `tests/e2e/gui-*.test.ts`
141
141
  (必需)。macOS 运行在确认 WindowServer 之前为试验性;它被保护起来,失败
142
142
  只记录日志而不标注运行。
143
- - `package` job 在组装发布之前构建 `gui.a` 与 `media.a`,因此两者都会随现有
144
- runtime 归档一起发布(`package-release` 复制整个 `runtime/`)。
145
- - `vendor/`(`gui.a` 的 SDL3/FreeType/HarfBuzz,以及 `media.a` 的 FFmpeg,
143
+ - `package` job 在组装发布之前构建 `gui.a`/`gui.lib` 与 `media.a`/`media.lib`,
144
+ 因此两者都会随现有 runtime 归档一起发布(`package-release` 复制整个
145
+ `runtime/`)。Windows x64 已包含;Windows arm64 仍跳过。
146
+ - `vendor/`(GUI 归档的 SDL3/FreeType/HarfBuzz,以及 `media` 的 FFmpeg,
146
147
  缓慢的部分)按 OS/arch 缓存,以 `scripts/build-gui.ts` /
147
- `scripts/build-media.ts` 为键。
148
- - Windows(构建 + 运行)在 CI 中保持试验性:MSVC 兼容的 `gui.lib` 可在本机
149
- 通过 SDL_GPU 的 Vulkan 后端构建并运行,但托管 runner 没有 GPU/Vulkan
150
- 驱动。失败只记录日志而不标注运行(见[待决问题](./gui/known-issues.md))。
148
+ `scripts/build-media.ts` 为键。Windows x64 有独立的源码 + FFmpeg 安装前缀
149
+ 缓存。
150
+ - Windows x64 在 CI 中构建两个归档并链接一个 `gui,media` 程序;托管 runner
151
+ 没有 GPU/Vulkan 驱动,因此 GUI/媒体示例的*运行*仍为试验性(失败只记录
152
+ 日志而不标注运行)。Windows arm64 仍跳过两个归档(见
153
+ [待决问题](./gui/known-issues.md))。CI 通过
154
+ `.github/actions/vs-toolchain` → `scripts/setup-vs-toolchain.ps1` 使用与
155
+ 本地构建相同的 Visual Studio MSVC + 自带 LLVM 工具链。
151
156
  8. **M8 — 交互式 DOM** ✅
152
157
  - 具有稳定标识的元素/文档句柄、通过运行时访问器读写属性、遍历/特性/查询、
153
158
  带有延迟重算样式/重新布局的变更
@@ -225,6 +230,47 @@ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
225
230
  通过与 SVG 文件相同的 NanoSVG 缓存(`svg.{h,cpp}`)解析并光栅化;markup
226
231
  缓存有界,DOM 变更会在下一次布局时重新序列化。e2e 见
227
232
  `tests/e2e/gui-inline-svg.test.ts`。
233
+ 17. **M17 — WebGL** ✅
234
+ - `canvas.getContext("webgl")` 创建真正的 GPU 上下文(`webgl.{h,cpp}`):
235
+ 一张离屏 RGBA8 颜色纹理加一张深度纹理、自己的 SDL_GPU 命令缓冲,并根据
236
+ 程序、顶点布局与固定功能状态惰性创建管线。页面通过既有图像路径直接合成
237
+ 颜色纹理,不需要 CPU 读回。
238
+ - `webgl_glsl*.cpp` 把 GLSL ES 1.00/3.00 改写为 Vulkan GLSL ES 3.10
239
+ (属性/`varying` 位置、`gl_FragColor`、`texture2D`、每阶段一个 std140
240
+ uniform 块、显式采样器绑定),用静态打包的 glslang 编译,反射 SPIR-V
241
+ 得到 uniform 偏移,并在 Metal 上用内置 SPIRV-Cross(`webgl_msl.cpp`)
242
+ 把同一份模块交叉编译为 MSL。
243
+ - `dom_api_webgl*.cpp` 暴露 WebGL 1.0 接口,包括纹理、mipmap、
244
+ 渲染到纹理的 framebuffer 与 `readPixels`。见 [WebGL](./gui/webgl.md);
245
+ e2e 见 `tests/e2e/gui-webgl.test.ts` 与
246
+ `tests/e2e/gui-example-webgl.test.ts`,示例见 `examples/gui/webgl-cube`。
247
+ 18. **M18 — WebGL 2** ✅
248
+ - `canvas.getContext("webgl2")` 返回的上下文原型继承 WebGL 1 原型,并带有
249
+ WebGL 2 常量与方法。
250
+ - GLSL ES 3.00 源码(`#version 300 es`、`in`/`out`、命名片元输出、
251
+ `gl_InstanceID`)走同一个改写器编译。
252
+ - 顶点数组对象保存/恢复属性表,实例化绘制使用 SDL 的按实例输入频率,采样器
253
+ 对象覆盖纹理单元的过滤/环绕状态。`texStorage2D`、`copyBufferSubData`、
254
+ `getBufferSubData` 与 `clearBuffer*` 已实现;查询/栅栏/UBO 与 transform
255
+ feedback 入口存在并优雅降级。见 [WebGL](./gui/webgl.md);e2e 见
256
+ `tests/e2e/gui-webgl2.test.ts` 与 `tests/e2e/gui-example-webgl2.test.ts`,
257
+ 示例见 `examples/gui/webgl2-cubes`。
258
+ 19. **M19 — 装饰性 CSS** ✅
259
+ - `@media` 块递归解析,并按视口求值(宽高范围、朝向、hover/pointer 与偏好
260
+ 特性);`matchMedia()` 使用同一个求值器。
261
+ - 生成内容:`::before`/`::after` 选择器、继承的伪样式、`content` 字符串/
262
+ 转义/`attr()`,以及不会泄漏到 DOM 遍历的合成布局盒。
263
+ - 多层 `background-image` 的线性与径向渐变,自下而上按纯色带绘制
264
+ (线性 18 条、径向 32 个同心椭圆)。
265
+ - `text-shadow` 作为阴影文本 run,并带九次采样模糊近似。
266
+ - `clip-path` 多边形(`inset`/`circle`/`ellipse`/`polygon`)解析到设备空间,
267
+ 用耳切法三角化,并在 `renderer_clip.cpp` 中与图形几何求交——不需要模板/
268
+ shader 改动。
269
+ - `filter` 颜色函数、九次采样 `blur()` 与轮廓 `drop-shadow()`;
270
+ `backdrop-filter` 会解析并参与层叠,但需要离屏背景通道(见
271
+ [已知问题](./gui/known-issues.md))。
272
+ - e2e 覆盖见 `tests/e2e/gui-effects.test.ts`;参见
273
+ [绘制](./gui/rendering.md#背景生成内容与特效m19)。
228
274
 
229
275
  ## 进度日志
230
276
 
@@ -252,10 +298,13 @@ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
252
298
  按绘制设备像素尺寸光栅化并按该尺寸缓存,因此缩放与 HiDPI 保持清晰。
253
299
  - **M6b** ✅ CSS transition(在 `style.*` 中解析、在 `document.*` 中维护动画
254
300
  时钟与 transition 状态、`advance`/`advance(ms)` 钩子、e2e 覆盖)。
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 中仍为试验性。
301
+ - **M7** ✅ 在 CI 中于 Linux、macOS 与 Windows x64 上构建 `gui.a`/`gui.lib` 与
302
+ `media.a`/`media.lib`(必需),并在 Linux 的 Xvfb 下运行示例与 GUI e2e 套件;
303
+ `package` 发布这些归档(Windows x64 已包含),`vendor/` 被缓存,`ar -M` 合并
304
+ 在 GNU/Linux、macOS 与 COFF/Windows 上可用。macOS 运行、Windows 示例的*运行*
305
+ 以及 Windows arm64 在 CI 中仍为试验性。Windows job 通过
306
+ `.github/actions/vs-toolchain` 使用与本地构建相同的 Visual Studio MSVC +
307
+ 自带 LLVM 工具链。
259
308
  - **M8** ✅ 元素/文档句柄(`dom_api.*`)、带延迟重算样式/重新布局的 DOM 变更
260
309
  (`document.*`、`xt_gui_flush_dom`)、带捕获/冒泡与 `stopPropagation` 的
261
310
  元素事件分发(`dom_api.*`、`gui.cpp`),以及
@@ -325,4 +374,30 @@ FFmpeg `7.1`(供可选的 `media` 归档使用;可用 `SDL3_TAG` /
325
374
  markup 采用有界 LRU)按绘制设备像素尺寸光栅化。`win.inlineSvg` 诊断钩子
326
375
  暴露序列化文档,`tests/e2e/gui-inline-svg.test.ts` 固定了尺寸、命中测试、
327
376
  渐变、CSS 盒样式与 DOM 变更。
377
+ - **M17** ✅ WebGL。`xtgui::WebGLContext`(`webgl.{h,cpp}`)拥有离屏颜色/深度
378
+ 目标与命令缓冲,`webgl_buffer/texture/draw/shader` 实现 GL 对象模型,
379
+ `webgl_glsl*.cpp` 用内置 glslang 把 GLSL ES 翻译为 SPIR-V
380
+ (`webgl_msl.cpp`/SPIRV-Cross 在 Metal 上把该模块转成 MSL),
381
+ `dom_api_webgl*.cpp` 绑定 WebGL 1.0 接口。`renderer_image.cpp` 按 canvas id
382
+ 返回上下文的颜色纹理,页面直接合成 GPU 输出。示例
383
+ `examples/gui/webgl-cube`;e2e 见 `tests/e2e/gui-webgl.test.ts` 与
384
+ `tests/e2e/gui-example-webgl.test.ts`。
385
+ - **M18** ✅ WebGL 2。`webgl2_proto()` 在 WebGL 1 原型上增加 WebGL 2 常量与
386
+ 方法;`webgl_webgl2.cpp` 实现顶点数组对象与采样器/查询/栅栏句柄,
387
+ `webgl_draw.cpp` 增加实例化绘制(由 `vertexAttribDivisor` 决定输入频率)与
388
+ 整数属性,`webgl_texture.cpp` 增加 `texStorage2D` 与 `clearBuffer*`。着色器
389
+ 改写器为 `#version 300 es` 输出分配连续 location,块反射会把结构体字段展开
390
+ 成 three.js 灯光可寻址的成员。three.js r160 已在真实渲染器上跑通基础/标准/
391
+ Phong 材质、纹理、灯光、雾、精灵、线段、点与实例化;Canvas2D 回退已删除。
392
+ 示例 `examples/gui/webgl2-cubes`(64 个立方体,一次实例化绘制);e2e 见
393
+ `tests/e2e/gui-webgl2.test.ts` 与 `tests/e2e/gui-example-webgl2.test.ts`。
394
+ - **M19** ✅ 装饰性 CSS。`css_sheet.cpp` 解析嵌套 `@media` 块,
395
+ `media_query.cpp` 按视口求值(`matchMedia` 也用它);`css_selector.cpp`
396
+ 识别 `::before`/`::after`。`style.cpp` 把伪样式算进每次重算样式时重建的
397
+ arena、解析 `content`,布局在真实子元素前后插入它们的盒子。
398
+ `gradient_values.cpp` 建模背景层列表(线性/径向、形状/尺寸/位置/色标),
399
+ `paint_background.cpp` 绘制它,`paint_effects.cpp` 应用滤镜颜色函数与九次
400
+ 采样模糊/投影并生成 `text-shadow` run,`paint_clip.cpp`/`renderer_clip.cpp`
401
+ 对三角化的 `clip-path` 多边形裁剪几何。e2e 见
402
+ `tests/e2e/gui-effects.test.ts`。
328
403
 
@@ -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。
@@ -30,7 +30,7 @@
30
30
 
31
31
  ## 其他表达式运算符
32
32
 
33
- - 逗号表达式 `,`
33
+ - 逗号表达式 `,`(降级为 `SequenceExpression`:从左到右求值每个操作数,结果为最后一个)
34
34
  - `in` 运算符(`key in obj`,映射 `xt_in`)
35
35
  - `delete obj.key` / `delete obj[key]`(映射 `xt_delete`)
36
36
  - `instanceof`(映射 `xt_instance_of`,沿原型链判断)
@@ -10,7 +10,7 @@
10
10
 
11
11
  - 变量声明:`var` / `let` / `const`,支持多声明符 `const a = 1, b = 2;`
12
12
  - 函数声明、函数表达式和方法,含 `async` 修饰、生成器(`function*`、`yield`、`yield*`、`.next`/`.throw`/`.return`)与异步生成器(`async function*`、`for await...of`)
13
- - `class` 声明 / 类表达式(构造函数、字段、方法、`static`、`extends`)
13
+ - `class` 声明 / 类表达式(构造函数、字段、方法、`static`、`static { ... }` 静态块、`extends`)
14
14
  - `if` / `else`
15
15
  - `while`、`do...while`
16
16
  - `for`(初始化、条件、增量均可省略)
@@ -27,8 +27,9 @@
27
27
  - 全部常见运算符及优先级 / 结合性(见[运算符](./operators.md))
28
28
  - 赋值表达式与全部复合赋值(见[运算符](./operators.md))
29
29
  - 条件(三元)表达式 `a ? b : c`
30
+ - 逗号(序列)表达式 `a, b, c`(可用于 `for` 头、括号组与表达式语句)
30
31
  - 箭头函数 `() => expr` / `() => { ... }`(含类型参数、返回类型注解)
31
- - 函数表达式 `function () {}` 与命名函数表达式 `function g() {}`
32
+ - 函数表达式 `function () {}` 与命名函数表达式 `function g() {}`(也支持 `async function` 表达式)
32
33
  - 调用表达式 `f(...)`、成员访问 `a.b`、元素访问 `a[i]`
33
34
  - 数组字面量 `[1, 2]`、稀疏数组 elision、展开 `[...a]`(也支持字符串、`Map`、`Set`)
34
35
  - 对象字面量 `{ a: 1 }`、简写属性 `{ a }`、方法简写 `{ m() {} }`、getter/setter 简写 `{ get x() {} }` / `{ set x(v) {} }`、计算属性名 `{ [expr]: 1 }`、对象展开 `{ ...obj }`
@@ -21,5 +21,7 @@ source.ts
21
21
  ```
22
22
 
23
23
  - 前端与后端、运行时、扩展完全解耦。
24
- - 流程由 `src/driver/compiler.ts` 串起:`读取 → 解析 → 绑定 → IR → 目标文件 → 链接`。前端位于 `src/driver/frontend.ts`,缓存键位于 `src/driver/build-key.ts`,运行时编译位于 `src/driver/runtime-objects.ts`,平台产物位于 `src/driver/app-artifacts.ts`。
24
+ - 流程由 `src/driver/compiler.ts` 串起:`读取 → 解析 → 绑定 → 检查 → IR → 目标文件 → 链接`。前端位于 `src/driver/frontend.ts`,缓存键位于 `src/driver/build-key.ts`,运行时编译位于 `src/driver/runtime-objects.ts`,平台产物位于 `src/driver/app-artifacts.ts`。
25
+ - [语义检查](./checker.md)(`src/checker/`)在绑定与代码生成之间运行,`--no-check` 可跳过。它把无需推断的检查(未定义名、重复声明、实参个数)与一个小型结构化类型模型结合起来(确定的可赋值性、属性形状、简单泛型与流收窄);类型语法随后仍然被擦除。
25
26
  - **自举**:`xbintsc` 可编译自身前端。用编译器构建 `src/cli/main.ts` 可得到可用的 `xbintsc` 二进制,且该二进制再自编译时产出的 LLVM IR 逐字节一致(源码 ≡ 第 1 代 ≡ 第 2 代 ≡ 第 3 代)。运行时仍为手写 C。
27
+ - **规范产物**:所有逐字节比较的产物在所有宿主上使用同一种编码。`src/canonical.ts` 定义 IR/调试信息/指纹的路径分隔符(`/`)与换行(LF),原生路径进入产物时用 `artifactPath()` 转换;运行时在渲染 `path` 结果与 `file://` URL 时使用 `XT_ARTIFACT_PATH_SEPARATOR`(`runtime/rt.h`)。面向用户的原生路径——诊断、`import.meta.filename`、`process.cwd()`——保留宿主分隔符,与 Node 一致。
@@ -13,7 +13,7 @@
13
13
  ## 对象
14
14
 
15
15
  - `Object.keys` / `values` / `entries` / `assign` / `getOwnPropertyNames` / `groupBy`,对象展开 `{...obj}`。
16
- - `Object.defineProperty` / `getOwnPropertyDescriptor(s)` —— 数据属性与访问器属性;属性标志会被报告,但后续写入/枚举尚未强制执行。
16
+ - `Object.defineProperty` / `defineProperties` / `getOwnPropertyDescriptor(s)` —— 数据属性与访问器属性,可单个也可批量定义;属性标志会被报告,但后续写入/枚举尚未强制执行。
17
17
  - `Object.freeze` / `is_frozen` / `from_entries`、`Object.getPrototypeOf`。
18
18
  - `Object.prototype`:`hasOwnProperty` / `toString` / `valueOf` / `isPrototypeOf` / `propertyIsEnumerable` / `__proto__`;`Object.getPrototypeOf({}) === Object.prototype`。
19
19
  - 一等公民内建构造器(`const A = Array`、`new A(...)`、`A.isArray`、`x instanceof A`)见[代码生成](./codegen.md)。
@@ -30,6 +30,7 @@
30
30
  - 数字格式化与强制转换与 Node 一致:`toFixed` / `toPrecision` / `toExponential`、十六 / 八 / 二进制解析,以及完整的 `+` / 关系运算 `ToPrimitive` 规则。这些由差分测试覆盖。
31
31
  - `BigInt` 字面量与值:任意精度算术、位运算与移位、比较、`toString(radix)`、`BigInt()`、`BigInt.asIntN` / `BigInt.asUintN`。
32
32
  - `Math`:完整函数与常量。
33
+ - `Math` 同时是一等对象:`const cos = Math.cos`、`[1, 2].map(Math.max)`、`const { sqrt, PI } = Math` 都能按值读取成员(`xt_math_object()` 为每个函数缓存一个原生闭包,读取开销仍然很低)。
33
34
  - `Number` 静态与 `Number()` 转换;`parseInt` / `parseFloat` / `isNaN` / `isFinite`。
34
35
 
35
36
  ## JSON