xbintsc 0.5.22 → 0.5.31

package/src/extensions/gui/index.ts

@@ -38,6 +38,62 @@ const guiModule: ExtensionModule = {
   },
 };
 
+/**
+ * Browser globals a script written for a real page expects to find.
+ *
+ * Every entry is a *value*, not a function: reading the identifier calls a
+ * runtime getter that returns the live host object, so `document.getElementById`
+ * or `new Image()` work without a `declare` in the source. The host objects are
+ * installed on the current window by `runtime/ext_gui/browser.cpp`.
+ *
+ * `xt_browser_type` carries the name as its argument, which is how one getter
+ * serves the whole family of DOM types, and `xt_browser_missing` is deliberately
+ * `undefined` so feature probes such as `typeof OffscreenCanvas === "undefined"`
+ * take the fallback path instead of calling a stub that does nothing.
+ */
+const hostTypes = [
+  "Image",
+  "Audio",
+  "AudioContext",
+  "webkitAudioContext",
+  "OffscreenCanvas",
+  "ImageBitmap",
+  "ImageData",
+  "HTMLCanvasElement",
+  "HTMLImageElement",
+  "HTMLVideoElement",
+  "HTMLAudioElement",
+  "HTMLElement",
+  "Element",
+  "Node",
+  "Event",
+  "CustomEvent",
+  "ProgressEvent",
+  "EventTarget",
+  "DOMParser",
+  "Request",
+  "Headers",
+  "Response",
+  "ReadableStream",
+  "WebGLRenderingContext",
+  "WebGL2RenderingContext",
+  "XRWebGLLayer",
+  "XRWebGLBinding",
+] as const;
+
+const browserGlobals: Record<string, { symbol: string; argument?: string }> = {
+  window: { symbol: "xt_browser_window" },
+  self: { symbol: "xt_browser_window" },
+  document: { symbol: "xt_browser_document" },
+  navigator: { symbol: "xt_browser_navigator" },
+  localStorage: { symbol: "xt_browser_local_storage" },
+  __THREE_DEVTOOLS__: { symbol: "xt_browser_missing" },
+  createImageBitmap: { symbol: "xt_browser_missing" },
+};
+for (const type of hostTypes) {
+  browserGlobals[type] = { symbol: "xt_browser_type", argument: type };
+}
+
 /** Absolute path to the per-platform prebuilt GUI archive (`gui.a`, or
  * `gui.lib` with the MSVC ABI on Windows). */
 function guiArchive(): string {
@@ -120,7 +176,16 @@ export const guiExtension: Extension = {
    */
   builtins: () => ({
     __registerScript: { symbol: "xt_register_script" },
+    requestAnimationFrame: { symbol: "xt_browser_request_animation_frame" },
+    cancelAnimationFrame: { symbol: "xt_browser_cancel_animation_frame" },
+    matchMedia: { symbol: "xt_browser_match_media" },
+    getComputedStyle: { symbol: "xt_browser_computed_style" },
+    escape: { symbol: "xt_browser_escape" },
+    alert: { symbol: "xt_browser_alert" },
+    prompt: { symbol: "xt_browser_prompt" },
   }),
+  /** Browser globals (`window`, `document`, the DOM type names). */
+  globalValues: () => browserGlobals,
   /** Rewrite imported `.html` assets (see `html.ts`). */
   assetLoaders: () => ({ ".html": loadHtmlAsset }),
 };

package/src/extensions/media/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Media extension: `<video>` / `<audio>` decoding for the GUI engine.
+ *
+ * The GUI extension is deliberately decoder-free: it models media elements,
+ * renders their frames and routes the DOM API, but keeps FFmpeg out of `gui.a`
+ * so a program that only needs windows and HTML/CSS does not pay for a media
+ * stack it never uses. This extension supplies the decoding half:
+ *
+ *   - `media.a` (built by `npm run media`) contains the FFmpeg-linked player
+ *     from `runtime/ext_media/media.cpp` and the static FFmpeg libraries;
+ *   - `runtime/ext_media/media_bridge.c` is compiled and linked directly. Its
+ *     constructor installs the player table into the GUI engine and references
+ *     the backend entry points, which makes the linker extract the archive
+ *     member — a static archive whose only entry point is a constructor would
+ *     otherwise never be pulled in.
+ *
+ * There is no importable TypeScript module: the feature is the DOM media
+ * surface that the `gui` module already exposes. Enable both extensions:
+ *
+ *     xbintsc run app.ts --ext gui,media
+ *
+ * The archive is POSIX-only for now (the build needs FFmpeg's `configure` and
+ * an MSVC-compatible FFmpeg has not been built), so Windows reports an
+ * actionable error instead of linking an inert element.
+ */
+
+import { join } from "node:path";
+import type { Extension } from "../registry.js";
+import { findRuntimeDir, platformSlug } from "../../driver/paths.js";
+import { findRuntimeLibrary } from "../../driver/runtime-lib.js";
+
+/** Absolute path to the per-platform prebuilt media archive. */
+function mediaArchive(): string {
+  return join(findRuntimeDir(), "lib", platformSlug(), "media.a");
+}
+
+export const mediaExtension: Extension = {
+  name: "media",
+  description: "Video/audio decoding for <video>/<audio> (requires gui, links FFmpeg)",
+  requires: ["gui"],
+  /**
+   * The registration bridge is a tiny C file linked as a normal object, so its
+   * constructor always runs. Keeping it out of `media.a` is what guarantees the
+   * archive is searched (see the header comment).
+   */
+  runtimeSources: () => [join(findRuntimeDir(), "ext_media", "media_bridge.c")],
+  nativeObjects: () => {
+    if (process.platform === "win32") {
+      throw new Error(
+        "the media extension is not available on Windows yet: it needs an MSVC-compatible " +
+          "FFmpeg build (see doc/gui/known-issues.md). Build without --ext media; media " +
+          "elements then report an 'error' event.",
+      );
+    }
+    const archive = findRuntimeLibrary("media");
+    if (archive === undefined) {
+      throw new Error(
+        `media native library not found at ${mediaArchive()} (or media.lib).\n` +
+          `Build it for ${platformSlug()} first with \`npm run media\` (see doc/gui/build.md).`,
+      );
+    }
+    return [archive];
+  },
+  /** `media.a` is C++ and FFmpeg itself needs libm; the GUI extension already
+   * contributes the C++ runtime and the OS frameworks. */
+  linkerFlags: () => (process.platform === "win32" ? [] : ["-lm"]),
+};

package/src/extensions/registry.ts

@@ -17,6 +17,23 @@ export interface BuiltinFunction {
   readonly returnVoid?: boolean;
 }
 
+/**
+ * A global *value* rather than a function: the name resolves to whatever a
+ * runtime getter returns, so `window`, `document` or a host constructor
+ * (`new AudioContext()`) can be reached without declaring them in the source.
+ *
+ * `symbol` has the usual `(int32_t argc, xt_value *argv)` ABI and is called
+ * with no arguments, or with one argument when `argument` is set (that is how
+ * a host hands a single getter a type name such as `"HTMLCanvasElement"`).
+ * `new Name(...)` lowers to the getter followed by an ordinary `xt_new`, so a
+ * host constructor is just a global value that returns a function.
+ */
+export interface GlobalValue {
+  readonly symbol: string;
+  /** Passed as the only argument; omit to call the getter with none. */
+  readonly argument?: string;
+}
+
 /**
  * One binding a Node-style module exports. It is either a direct runtime
  * function with the uniform `(argc, argv)` ABI (`symbol`), or a named method
@@ -59,6 +76,14 @@ export interface AssetLoadResult {
    * contain its own `import`/`export` statements, which are followed normally.
    */
   readonly moduleSource: string;
+  /**
+   * Ranges of `moduleSource` that were copied verbatim from *another* file —
+   * for instance the body of `<script src="app.js">` wrapped by the `gui`
+   * `.html` loader. Nodes inside a range keep that file as their origin, so
+   * diagnostics name the file the user actually wrote and the checker's
+   * plain-JavaScript exemption still applies to a `.js` script.
+   */
+  readonly sourceRanges?: readonly AssetSourceRange[];
   /**
    * Extra files the transformed module depends on that are *not* reached
    * through imports (for cache invalidation). Imported files are already
@@ -67,6 +92,13 @@ export interface AssetLoadResult {
   readonly dependencies?: readonly string[];
 }
 
+/** A `[start, end)` span of a generated module copied from `file`. */
+export interface AssetSourceRange {
+  readonly start: number;
+  readonly end: number;
+  readonly file: string;
+}
+
 /** Rewrites an imported file (selected by extension) into a TS module. */
 export type AssetLoader = (path: string, source: string) => AssetLoadResult;
 
@@ -74,6 +106,12 @@ export interface Extension {
   readonly name: string;
   /** Description shown by `xbintsc ext list`. */
   readonly description?: string;
+  /**
+   * Other extensions this one needs. The registry rejects a build that enables
+   * it without them, so a dependent extension fails with an actionable message
+   * instead of an unresolved symbol at link time (e.g. `media` needs `gui`).
+   */
+  readonly requires?: readonly string[];
   /** C/asm sources compiled and linked alongside the generated module. */
   runtimeSources?(): readonly string[];
   /**
@@ -91,6 +129,12 @@ export interface Extension {
   linkerFlags?(): readonly string[];
   /** Global identifiers that resolve to runtime symbols when called. */
   builtins?(): Readonly<Record<string, BuiltinFunction>>;
+  /**
+   * Global identifiers that resolve to a runtime *value* (`window`,
+   * `document`, a host constructor). They need no declaration in the source
+   * and are not callable-by-name: reading the identifier calls the getter.
+   */
+  globalValues?(): Readonly<Record<string, GlobalValue>>;
   /** Modules importable as `import ... from "<specifier>"`. */
   modules?(): Readonly<Record<string, ExtensionModule>>;
   /**
@@ -145,6 +189,24 @@ export class ExtensionRegistry {
     return this.extensions.delete(name);
   }
 
+  /**
+   * Throw when a registered extension requires one that is not registered.
+   * Called before a build so `--ext media` without `--ext gui` reports which
+   * flags to pass instead of failing later with an unresolved symbol.
+   */
+  validate(): this {
+    for (const extension of this.extensions.values()) {
+      for (const dependency of extension.requires ?? []) {
+        if (this.extensions.has(dependency)) continue;
+        throw new Error(
+          `extension '${extension.name}' requires the '${dependency}' extension; ` +
+            `pass --ext ${dependency},${extension.name}`,
+        );
+      }
+    }
+    return this;
+  }
+
   get(name: string): Extension | undefined {
     return this.extensions.get(name);
   }
@@ -167,6 +229,16 @@ export class ExtensionRegistry {
     return merged;
   }
 
+  /** Flatten every registered extension's global values into one lookup. */
+  globalValues(): Readonly<Record<string, GlobalValue>> {
+    const merged: Record<string, GlobalValue> = {};
+    for (const extension of this.extensions.values()) {
+      const values = extension.globalValues?.();
+      if (values) Object.assign(merged, values);
+    }
+    return merged;
+  }
+
   /** Flatten every registered extension's importable modules. */
   modules(): Readonly<Record<string, ExtensionModule>> {
     const merged: Record<string, ExtensionModule> = {};

package/src/index.ts

@@ -19,6 +19,7 @@ export { TokenKind, KEYWORDS, type Token } from "./lexer/token.js";
 export * from "./ast/nodes.js";
 export { Parser } from "./parser/parser.js";
 export { bind, SymbolKind, ScopeKind, type BindResult, type FunctionInfo, type SymbolInfo } from "./binder/binder.js";
+export { checkProgram, type CheckOptions } from "./checker/checker.js";
 export { generate, type CodegenResult, type CodegenOptions } from "./codegen/llvm.js";
 export {
   XT_UNDEFINED,
@@ -32,6 +33,7 @@ export {
 export { ExtensionRegistry, createDefaultRegistry, coreExtension, type Extension, type ExtensionModule, type ModuleExport, type ModuleExports, type AssetLoader, type AssetLoadResult } from "./extensions/registry.js";
 export { bundledExtensions } from "./extensions/catalog.js";
 export { nodeExtension } from "./extensions/node/index.js";
+export { mediaExtension } from "./extensions/media/index.js";
 export type { NodeModule } from "./extensions/node/module.js";
 export {
   NativeExtensionError,

package/src/parser/declarations/classes.ts

@@ -85,6 +85,13 @@ export const declarationClassMethods: DeclarationClassMethods = {
       this.nextToken();
       return undefined;
     }
+    /* `static { ... }`: a block that runs once while the class is defined. The
+     * `static` keyword was already consumed by `tryParseModifiers`, so the
+     * initializer position is the only way to tell it apart from a member. */
+    if (this.at(TokenKind.OpenBrace) && this.hasModifier(modifiers, ModifierKind.Static)) {
+      const body = this.parseBlock();
+      return { kind: SyntaxKind.ClassStaticBlockDeclaration, modifiers, body, start, end: body.end };
+    }
     if (
       (this.at(TokenKind.GetKeyword) || this.at(TokenKind.SetKeyword)) &&
       !this.atAhead(1, TokenKind.OpenParen) &&

package/src/parser/expressions.ts

@@ -61,7 +61,19 @@ export interface ExpressionMethods {
 
 export const expressionMethods: ExpressionMethods = {
   parseExpression(this: Parser, noIn = false): Expression {
-    return this.parseAssignmentExpression(noIn);
+    const first = this.parseAssignmentExpression(noIn);
+    if (!this.at(TokenKind.Comma)) return first;
+    const expressions: Expression[] = [first];
+    while (this.at(TokenKind.Comma)) {
+      this.nextToken();
+      expressions.push(this.parseAssignmentExpression(noIn));
+    }
+    return {
+      kind: SyntaxKind.SequenceExpression,
+      expressions,
+      start: first.start,
+      end: expressions[expressions.length - 1]!.end,
+    };
   },
 
   parseAssignmentExpression(this: Parser, noIn = false): Expression {

package/src/parser/literals.ts

@@ -159,8 +159,12 @@ export const literalMethods: LiteralMethods = {
   },
 
   parseFunctionExpression(this: Parser): FunctionExpression {
-    const start = this.parseExpected(TokenKind.FunctionKeyword).start;
-    let flags = NodeFlags.None;
+    /* `async function (...) {}` is an expression too; the `async` keyword is
+     * part of this node rather than a modifier list. */
+    const asyncToken = this.at(TokenKind.AsyncKeyword) ? this.nextToken() : undefined;
+    const functionToken = this.parseExpected(TokenKind.FunctionKeyword);
+    const start = asyncToken ? asyncToken.start : functionToken.start;
+    let flags = asyncToken ? NodeFlags.Async : NodeFlags.None;
     if (this.at(TokenKind.Asterisk)) {
       this.nextToken();
       flags |= NodeFlags.Generator;