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