xbintsc 0.3.46 → 0.3.61

package/src/cli/hints.ts

@@ -0,0 +1,194 @@
+/**
+ * Documentation pointers for diagnostics.
+ *
+ * Every failure printed by the CLI ends with a `hint:` line naming the document
+ * that explains what to do next. The messages already say what is wrong; these
+ * lines say where to read more, which is what keeps an agent (or a person) from
+ * re-deriving the language subset one failed build at a time.
+ *
+ * The paths are relative to the repository root, so they stay clickable in
+ * GitHub's rendered output and on a terminal that links paths.
+ */
+
+import { DiagnosticCode, type Diagnostic } from "../diagnostics/diagnostic.js";
+
+/** Where a reader should go next. */
+export interface DocumentationPointer {
+  /** Message printed after `hint:`. */
+  readonly text: string;
+  /** Repository-relative path to the document. */
+  readonly path: string;
+}
+
+export const DOC_LANGUAGE_SUPPORT = "doc/ai/language-support.md";
+export const DOC_EXTENSIONS = "doc/ai/extensions.md";
+export const DOC_TROUBLESHOOTING = "doc/ai/troubleshooting.md";
+export const DOC_CLI = "doc/ai/cli.md";
+export const DOC_REQUIREMENTS = "doc/requirements.md";
+
+const CHECKER_HINT: DocumentationPointer = {
+  text: "the compiler supports a subset of TypeScript; check what is implemented before rewriting",
+  path: DOC_LANGUAGE_SUPPORT,
+};
+
+const REQUIREMENT_HINT: DocumentationPointer = {
+  text: "xbintsc needs clang 16 or newer; run `xbintsc doctor` to see the resolved toolchain",
+  path: DOC_REQUIREMENTS,
+};
+
+/** Hint for a clang failure: a missing or too-old clang has a specific answer. */
+export function toolchainPointer(message: string): DocumentationPointer {
+  const usesTypedPointers = /defined with type '\[.*i8\]\*' but expected 'i8\*'/.test(message);
+  if (usesTypedPointers || /No C compiler found/i.test(message)) return REQUIREMENT_HINT;
+  return {
+    text: "read the clang output above, then the toolchain section of the troubleshooting guide",
+    path: DOC_TROUBLESHOOTING,
+  };
+}
+
+/** A thrown failure the CLI can name, in table order. */
+export interface ThrownFailure {
+  /** Tested against the thrown message. */
+  readonly match: RegExp;
+  readonly code: DiagnosticCode;
+  readonly pointer: DocumentationPointer;
+}
+
+/**
+ * Failures the CLI reports as a message instead of a diagnostic. Matching on the
+ * text is what lets each one reach the document that actually explains it —
+ * a missing manifest and an unknown extension are both "cannot read something",
+ * but only one of them is answered by the CLI reference.
+ */
+const THROWN_FAILURES: readonly ThrownFailure[] = [
+  {
+    match: /native extension manifest/i,
+    code: DiagnosticCode.IOError,
+    pointer: {
+      text: "check the manifest path and its JSON; objects are relative to the manifest file",
+      path: DOC_EXTENSIONS,
+    },
+  },
+  {
+    match: /Unknown extension/i,
+    code: DiagnosticCode.IOError,
+    pointer: {
+      text: "run `xbintsc help` for the flag, and see the built-in extensions this build ships",
+      path: DOC_EXTENSIONS,
+    },
+  },
+  {
+    match: /config|JSON/i,
+    code: DiagnosticCode.IOError,
+    pointer: {
+      text: "check the project config path and its fields",
+      path: DOC_CLI,
+    },
+  },
+];
+
+/** The failure a thrown error's message describes, if any. */
+export function thrownFailure(message: string): ThrownFailure | undefined {
+  return THROWN_FAILURES.find((failure) => failure.match.test(message));
+}
+
+/**
+ * The completion for an unclassified thrown error: the toolchain's own wording
+ * is the only thing worth directing a reader to.
+ */
+export const UNEXPECTED_FAILURE_HINT: DocumentationPointer = {
+  text: "this failure has no dedicated guide; check the resolved toolchain and the source paths",
+  path: DOC_TROUBLESHOOTING,
+};
+
+/**
+ * The document that explains a diagnostic, or `undefined` for internal errors
+ * that no reader can act on.
+ */
+export function documentationFor(diagnostic: Diagnostic): DocumentationPointer | undefined {
+  switch (diagnostic.code) {
+    // Lexer, parser and binder report a precise location; the guidance is the
+    // same subset reference.
+    case DiagnosticCode.UnterminatedString:
+    case DiagnosticCode.UnterminatedTemplate:
+    case DiagnosticCode.UnterminatedComment:
+    case DiagnosticCode.InvalidCharacter:
+    case DiagnosticCode.InvalidNumber:
+    case DiagnosticCode.InvalidEscape:
+    case DiagnosticCode.UnexpectedToken:
+    case DiagnosticCode.ExpectedToken:
+    case DiagnosticCode.ExpectedIdentifier:
+    case DiagnosticCode.UnexpectedEof:
+    case DiagnosticCode.InvalidAssignmentTarget:
+    case DiagnosticCode.DuplicateDefault:
+    case DiagnosticCode.InvalidTypeSyntax:
+    case DiagnosticCode.DuplicateIdentifier:
+    case DiagnosticCode.CannotFindName:
+    case DiagnosticCode.IllegalRedeclaration:
+    case DiagnosticCode.CannotAssignToConst:
+    case DiagnosticCode.UnsupportedFeature:
+      return CHECKER_HINT;
+
+    // Every codegen and bundler error carries its own message; the subset page
+    // is what separates "you wrote unsupported code" from "you wrote a bug".
+    case DiagnosticCode.CodegenError:
+      return CHECKER_HINT;
+
+    case DiagnosticCode.ModuleNotFound:
+      return {
+        text: "Node modules need the `node` extension (`--ext node`); third-party npm packages are not supported",
+        path: DOC_EXTENSIONS,
+      };
+
+    case DiagnosticCode.IOError:
+      return {
+        text: "check the path and the project config; paths in xbintsc.config.json resolve against that file",
+        path: DOC_TROUBLESHOOTING,
+      };
+
+    case DiagnosticCode.ToolchainError:
+      return toolchainPointer(diagnostic.message);
+
+    case DiagnosticCode.IncrementalCacheError:
+      return {
+        text: "the incremental cache could not be trusted; retry with `--force` or remove the cache directory",
+        path: DOC_CLI,
+      };
+
+    // The checker codes are defined but never emitted today.
+    case DiagnosticCode.TypeMismatch:
+    case DiagnosticCode.NotCallable:
+    case DiagnosticCode.PropertyNotFound:
+    case DiagnosticCode.ArgumentCountMismatch:
+      return CHECKER_HINT;
+  }
+}
+
+/** Render one `hint:` line, or `undefined` when the code has no document. */
+export function formatDocumentationHint(diagnostic: Diagnostic): string | undefined {
+  const pointer = documentationFor(diagnostic);
+  if (!pointer) return undefined;
+  return `hint: ${pointer.text} — see ${pointer.path}`;
+}
+
+/**
+ * One hint line per failing diagnostic, in first-seen order and without
+ * repeating a document the reader has already been sent to.
+ */
+export function documentationHints(diagnostics: readonly Diagnostic[]): string[] {
+  const lines: string[] = [];
+  const seen = new Set<string>();
+  for (const diagnostic of diagnostics) {
+    if (diagnostic.category !== "error") continue;
+    const line = formatDocumentationHint(diagnostic);
+    if (line === undefined || seen.has(line)) continue;
+    seen.add(line);
+    lines.push(line);
+  }
+  return lines;
+}
+
+/** Render one hint line for an already-classified thrown failure. */
+export function formatThrownHint(pointer: DocumentationPointer): string {
+  return `hint: ${pointer.text} — see ${pointer.path}`;
+}

package/src/cli/main.ts

@@ -22,7 +22,16 @@ import { build, compileEntry, COMPILER_VERSION, type EmitKind } from "../driver/
 import { findRuntimeDir, platformSlug } from "../driver/paths.js";
 import { runtimeLibDir } from "../driver/runtime-lib.js";
 import { resolveToolchain } from "../driver/toolchain-provider.js";
-import { realRunner } from "../driver/toolchain.js";
+import { realRunner, ToolchainError } from "../driver/toolchain.js";
+import {
+  DOC_CLI,
+  DOC_TROUBLESHOOTING,
+  documentationHints,
+  thrownFailure,
+  toolchainPointer,
+  UNEXPECTED_FAILURE_HINT,
+  type DocumentationPointer,
+} from "./hints.js";
 import { createDefaultRegistry, type ExtensionRegistry } from "../extensions/registry.js";
 import { bundledExtensions } from "../extensions/catalog.js";
 import { nativeExtensionFromManifest } from "../extensions/native.js";
@@ -46,6 +55,13 @@ const defaultIo: CliIo = {
   stderr: (text) => process.stderr.write(text),
 };
 
+/**
+ * `--no-hints` state for the current {@link run} call. A module-level flag (and
+ * not a parameter) keeps the hint layer out of the signatures of every helper
+ * that can fail.
+ */
+let hintsDisabled = false;
+
 interface ParsedArgs {
   readonly command?: string;
   readonly positionals: string[];
@@ -152,6 +168,46 @@ function printDiagnostics(diagnostics: readonly Diagnostic[], fileName: string,
     }
     io.stderr(formatDiagnostic(diagnostic, source) + "\n");
   }
+  for (const hint of documentationHints(diagnostics)) emitHint(io, hint);
+}
+
+/** Print one `hint:` line unless the caller asked for plain output. */
+function emitHint(io: CliIo, line: string): void {
+  if (hintsDisabled) return;
+  io.stderr(`${line}\n`);
+}
+
+/**
+ * Report a failure that threw instead of becoming a diagnostic, ending with the
+ * documentation pointer that explains it. Without this a toolchain failure is a
+ * raw stack trace, which tells a reader nothing about which document answers
+ * the question.
+ */
+function reportThrown(error: unknown, io: CliIo): number {
+  const message =
+    error instanceof ToolchainError
+      ? `xbintsc: ${error.message}`
+      : `xbintsc: ${error instanceof Error ? error.message : String(error)}`;
+  io.stderr(`${message.trimEnd()}\n`);
+  const text = error instanceof ToolchainError ? error.message : message;
+  const pointer = error instanceof ToolchainError ? toolchainPointer(text) : thrownPointer(text);
+  emitHint(io, `hint: ${pointer.text} — see ${pointer.path}`);
+  return 1;
+}
+
+/** The document that explains a failure the CLI reports as a plain message. */
+function thrownPointer(message: string): DocumentationPointer {
+  return thrownFailure(message)?.pointer ?? UNEXPECTED_FAILURE_HINT;
+}
+
+/** Report a project-config failure, which never becomes a diagnostic bag. */
+function reportConfigError(error: string, io: CliIo): number {
+  io.stderr(`xbintsc: ${error}\n`);
+  const pointer = /JSON/i.test(error)
+    ? `hint: fix the JSON; an unreadable or malformed config fails the build — see ${DOC_TROUBLESHOOTING}`
+    : `hint: check the config path and its fields — see ${DOC_CLI}`;
+  emitHint(io, pointer);
+  return 1;
 }
 
 const HELP = `xbintsc ${COMPILER_VERSION} - TypeScript binary compiler
@@ -181,6 +237,14 @@ Options:
       --app-id <id>     macOS bundle identifier (e.g. com.example.demo)
       --force           Ignore the incremental cache
       --verbose         Print progress information
+      --no-hints        Do not append the "hint: … see <doc>" line to failures
+
+xbintsc compiles a subset of TypeScript to a native binary. Types are erased
+(never checked), Node modules need --ext node, third-party npm imports are not
+supported, and clang 16+ is required to link.
+
+Docs: doc/ai/README.md (task guide) - doc/ai/language-support.md (subset) -
+doc/ai/troubleshooting.md (failures) - llms.txt (index of every document)
 `;
 
 function firstLine(text: string): string {
@@ -281,6 +345,19 @@ function listFlag(flags: Map<string, string | boolean>, name: string): string[]
 }
 
 export function run(argv: readonly string[], io: CliIo = defaultIo): number {
+  const disableHints = parseArgs(argv).flags.has("no-hints");
+  const previous = hintsDisabled;
+  hintsDisabled = disableHints;
+  try {
+    return dispatch(argv, io);
+  } catch (error) {
+    return reportThrown(error, io);
+  } finally {
+    hintsDisabled = previous;
+  }
+}
+
+function dispatch(argv: readonly string[], io: CliIo): number {
   const args = parseArgs(argv);
   const command = args.command;
 
@@ -301,13 +378,11 @@ export function run(argv: readonly string[], io: CliIo = defaultIo): number {
   if (command === "emit") {
     const cliEntry = args.positionals[0];
     const resolved = resolveProjectConfig(args.flags, cliEntry);
-    if (!resolved.ok) {
-      io.stderr(`xbintsc: ${resolved.error}\n`);
-      return 1;
-    }
+    if (!resolved.ok) return reportConfigError(resolved.error, io);
     const entry = cliEntry ?? resolved.config.entry;
     if (!entry) {
       io.stderr(`xbintsc: emit requires a source file (or 'entry' in ${CONFIG_FILE_NAME})\n`);
+      emitHint(io, `hint: pass the entry file, or set 'entry' in ${CONFIG_FILE_NAME} — see ${DOC_CLI}`);
       return 1;
     }
     const extNames = listFlag(args.flags, "ext") ?? resolved.config.extensions ?? [];
@@ -325,14 +400,12 @@ export function run(argv: readonly string[], io: CliIo = defaultIo): number {
   if (command === "build" || command === "run") {
     const cliEntry = args.positionals[0];
     const resolved = resolveProjectConfig(args.flags, cliEntry);
-    if (!resolved.ok) {
-      io.stderr(`xbintsc: ${resolved.error}\n`);
-      return 1;
-    }
+    if (!resolved.ok) return reportConfigError(resolved.error, io);
     const config = resolved.config;
     const entry = cliEntry ?? config.entry;
     if (!entry) {
       io.stderr(`xbintsc: ${command} requires a source file (or 'entry' in ${CONFIG_FILE_NAME})\n`);
+      emitHint(io, `hint: pass the entry file, or set 'entry' in ${CONFIG_FILE_NAME} — see ${DOC_CLI}`);
       return 1;
     }
     const emit = (args.flags.get("emit") as EmitKind | undefined) ?? "exe";

package/src/codegen/generator/tables.ts

@@ -327,27 +327,73 @@ export const KIND_NAMES = new Map<number, string>([
   [SyntaxKind.SwitchStatement, "switch statement"],
 ]);
 
+/**
+ * The UTF-8 bytes of one code point, which must be an ASCII byte or a Unicode
+ * scalar (`0..0x10ffff`, not a surrogate). Encoded by hand rather than with
+ * `String.fromCharCode`/`String.fromCodePoint`, which a self-hosted build would
+ * run through the runtime and encode a second time.
+ */
+export function codePointBytes(code: number): number[] {
+  if (code < 0x80) return [code];
+  if (code < 0x800) return [0xc0 | (code >> 6), 0x80 | (code & 0x3f)];
+  if (code < 0x10000) return [0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f)];
+  return [
+    0xf0 | (code >> 18),
+    0x80 | ((code >> 12) & 0x3f),
+    0x80 | ((code >> 6) & 0x3f),
+    0x80 | (code & 0x3f),
+  ];
+}
+
+/**
+ * The bytes a string literal stands for.
+ *
+ * A compiled string is a sequence of UTF-8 bytes (`"é".length` is 1 and
+ * `"😀".length` is 4 - see doc/ai/language-support.md). The text reaching this
+ * point is whatever a host's strings are, and both shapes have to produce the
+ * same bytes:
+ *
+ * - a UTF-16 host decodes a file into characters, so `é` is one code unit
+ *   (0xe9) and has to be encoded here;
+ * - the self-hosted runtime has no UTF-8 decoder, so `readFileSync` hands over
+ *   a file's bytes, and `é` is already `c3 a9`. Encoding that again is what
+ *   turned the three bytes of `—` into six and broke the self-hosting fixpoint.
+ *
+ * A code unit above 0xff can only be text, so its presence settles which shape
+ * this is: text is encoded (once), and text that is already a byte sequence is
+ * emitted as it is. A source file read on either host therefore lands on the
+ * same bytes, which is what the fixpoint needs.
+ */
 export function utf8Bytes(text: string): number[] {
+  if (!hasMultiByteUnit(text)) {
+    const bytes: number[] = [];
+    for (let index = 0; index < text.length; index++) bytes.push(text.charCodeAt(index) & 0xff);
+    return bytes;
+  }
   const bytes: number[] = [];
-  for (const character of text) {
-    const code = character.codePointAt(0)!;
-    if (code < 0x80) bytes.push(code);
-    else if (code < 0x800) {
-      bytes.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
-    } else if (code < 0x10000) {
-      bytes.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
-    } else {
-      bytes.push(
-        0xf0 | (code >> 18),
-        0x80 | ((code >> 12) & 0x3f),
-        0x80 | ((code >> 6) & 0x3f),
-        0x80 | (code & 0x3f),
-      );
+  const length = text.length;
+  for (let index = 0; index < length; index++) {
+    let code = text.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff && index + 1 < length) {
+      const low = text.charCodeAt(index + 1);
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        code = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+        index++;
+      }
     }
+    for (const byte of codePointBytes(code)) bytes.push(byte);
   }
   return bytes;
 }
 
+/** Whether any code unit is above one byte, which means text, not bytes. */
+function hasMultiByteUnit(text: string): boolean {
+  for (let index = 0; index < text.length; index++) {
+    if (text.charCodeAt(index) > 0xff) return true;
+  }
+  return false;
+}
+
 export function escapeBytes(bytes: readonly number[]): string {
   return bytes
     .map((byte) => {

package/src/diagnostics/source-text.ts

@@ -0,0 +1,78 @@
+/**
+ * Source text is a byte sequence.
+ *
+ * A compiled string is a sequence of UTF-8 bytes (`"e".length` is 1 for an
+ * accent and 4 for an emoji - see doc/ai/language-support.md), and the compiler
+ * is built by itself: there the self-hosted `readFileSync` hands the scanner a
+ * file's own bytes, one per code unit, and the runtime has no UTF-8 decoder to
+ * change that. A host whose strings are UTF-16 must be given the text in the
+ * same shape, or the same program emits different bytes depending on which
+ * generation of the compiler read it - which is how a non-ASCII literal ended
+ * up double-encoded and broke the self-hosting fixpoint.
+ *
+ * `sourceTextBytes` is that shape: a source file's bytes, one code unit each.
+ * The driver reads every source file through it, and codegen emits those bytes
+ * unchanged.
+ */
+
+/**
+ * The UTF-8 bytes of `text`, one code unit each. Text that is already a byte
+ * sequence is kept as it is, so this is idempotent and safe to apply to a read
+ * on either host.
+ */
+export function sourceTextBytes(text: string): string {
+  if (!hasCharacter(text)) return startsWithBom(text) ? text.slice(3) : text;
+  const encoded = encodeUtf8(text);
+  return startsWithBom(encoded) ? encoded.slice(3) : encoded;
+}
+
+/** Encode text as UTF-8, spelled one code unit per byte. */
+function encodeUtf8(text: string): string {
+  const chunks: string[] = [];
+  const units: number[] = [];
+  for (let index = 0; index < text.length; index++) {
+    let code = text.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff && index + 1 < text.length) {
+      const low = text.charCodeAt(index + 1);
+      if (low >= 0xdc00 && low <= 0xdfff) {
+        code = 0x10000 + ((code - 0xd800) << 10) + (low - 0xdc00);
+        index++;
+      }
+    }
+    if (code < 0x80) units.push(code);
+    else if (code < 0x800) units.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+    else if (code < 0x10000) {
+      units.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+    } else {
+      units.push(
+        0xf0 | (code >> 18),
+        0x80 | ((code >> 12) & 0x3f),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f),
+      );
+    }
+    if (units.length >= 512) flushUnits(units, chunks);
+  }
+  flushUnits(units, chunks);
+  return chunks.join("");
+}
+
+/** Whether any code unit is above one byte, which means text, not bytes. */
+function hasCharacter(text: string): boolean {
+  for (let index = 0; index < text.length; index++) {
+    if (text.charCodeAt(index) > 0xff) return true;
+  }
+  return false;
+}
+
+/** Whether a decoded read started with a UTF-8 byte order mark. */
+function startsWithBom(text: string): boolean {
+  return text.charCodeAt(0) === 0xef && text.charCodeAt(1) === 0xbb && text.charCodeAt(2) === 0xbf;
+}
+
+/** Append the pending code units as one chunk of the byte string. */
+function flushUnits(units: number[], chunks: string[]): void {
+  if (units.length === 0) return;
+  chunks.push(String.fromCharCode(...units));
+  units.length = 0;
+}

package/src/driver/bundler/graph.ts

@@ -9,6 +9,7 @@ import { SyntaxKind, type ExportDeclaration, type ImportDeclaration, type Statem
 import { bind } from "../../binder/binder.js";
 import { DiagnosticBag, DiagnosticCode } from "../../diagnostics/diagnostic.js";
 import { SourceFile } from "../../diagnostics/source.js";
+import { sourceTextBytes } from "../../diagnostics/source-text.js";
 import { Parser } from "../../parser/parser.js";
 import type { AssetLoader } from "../../extensions/registry.js";
 import { classifyDependency } from "./resolve.js";
@@ -53,7 +54,7 @@ export function loadGraph(
       return undefined;
     }
     visiting.add(path);
-    const raw = readFileSync(path, "utf8");
+    const raw = sourceTextBytes(readFileSync(path, "utf8"));
     /* An extension may rewrite an imported asset (e.g. `.html`) into a TS
      * module before it is parsed. The core only sees the transformed text. */
     const loader = assetLoaders[extname(path).toLowerCase()];

package/src/driver/compiler.ts

@@ -11,6 +11,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from
 import { basename, extname, join, resolve } from "node:path";
 import { DiagnosticBag, DiagnosticCode, type Diagnostic } from "../diagnostics/diagnostic.js";
 import { SourceFile } from "../diagnostics/source.js";
+import { sourceTextBytes } from "../diagnostics/source-text.js";
 import { Parser } from "../parser/parser.js";
 import { generate } from "../codegen/llvm.js";
 import { SyntaxKind } from "../ast/nodes.js";
@@ -22,6 +23,7 @@ import { findRuntimeLibrary } from "./runtime-lib.js";
 import { resolveToolchain } from "./toolchain-provider.js";
 import { ensureIconObject, readIcon, EMPTY_ICON, IconError, type IconInfo } from "./icon.js";
 import { ensureWindowsIconResource, resolveResourceCompiler } from "./win-icon.js";
+import { ensureWindowsEntryObject } from "./win-entry.js";
 import { bundlePathFor, packageMacApp } from "./mac-bundle.js";
 import type { AppConfig } from "./config.js";
 import {
@@ -106,7 +108,7 @@ function externalModuleSpecifiers(registry: ExtensionRegistry): Set<string> {
  */
 export function compileEntry(entryPath: string, extensions?: ExtensionRegistry): CompileStringResult {
   const absoluteEntry = resolve(entryPath);
-  const sourceText = readFileSync(absoluteEntry, "utf8");
+  const sourceText = sourceTextBytes(readFileSync(absoluteEntry, "utf8"));
   const file = new SourceFile(absoluteEntry, sourceText);
   const diagnostics = new DiagnosticBag();
   const parser = new Parser(file, diagnostics);
@@ -170,7 +172,7 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
   const optimize = options.optimize ?? "2";
 
   const absoluteEntry = resolve(entryPath);
-  const sourceText = readFileSync(absoluteEntry, "utf8");
+  const sourceText = sourceTextBytes(readFileSync(absoluteEntry, "utf8"));
 
   const baseName = basename(absoluteEntry, extname(absoluteEntry));
   const outputPath =
@@ -294,6 +296,18 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
     toolchain.env,
   );
 
+  /* On Windows a GUI program links as a **Windows-subsystem** executable, so
+   * launching it does not flash a console window. That subsystem's C runtime
+   * wants `WinMain`, so a tiny shim object bridges it to the runtime's `main`.
+   * `app.console: true` keeps the console subsystem instead (useful while
+   * debugging, because stdout and stderr only exist there). Other platforms
+   * have no equivalent. */
+  const windowsSubsystem = process.platform === "win32" && registry.has("gui") && app.console !== true;
+  const consoleSubsystem = windowsSubsystem ? ["-Wl,/SUBSYSTEM:WINDOWS"] : [];
+  const entryObject = windowsSubsystem
+    ? ensureWindowsEntryObject(runner, clang, cacheDir, toolchain.env)
+    : undefined;
+
   const iconObjects: string[] = [];
   // The GUI extension references the icon symbols unconditionally, so a GUI
   // program gets an (empty) icon object even with no icon configured.
@@ -319,12 +333,24 @@ export function build(entryPath: string, options: BuildOptions = {}): BuildResul
 
   link(runner, {
     clang,
-    objectPaths: [objectPath, ...runtimeObjects, ...extensionObjects, ...nativeObjects, ...iconObjects],
+    objectPaths: [
+      objectPath,
+      ...runtimeObjects,
+      ...extensionObjects,
+      ...nativeObjects,
+      ...(entryObject !== undefined ? [entryObject] : []),
+      ...iconObjects,
+    ],
     outputPath,
     linkerFlags: [
       ...toolchain.linkerArgs,
       ...(process.platform === "win32" ? ["-lws2_32"] : ["-lm"]),
       ...registry.linkerFlags(),
+      /* A GUI program is a Windows-subsystem executable: no console window is
+       * created when it is launched. Console output (stdout/stderr) is lost in
+       * that subsystem, so a program that wants to report things opts back in
+       * with `app.console: true`. */
+      ...consoleSubsystem,
     ],
     optimize,
     env: toolchain.env,

package/src/driver/config.ts

@@ -24,6 +24,13 @@ export interface AppConfig {
   /** macOS only: produce a `<name>.app` bundle. */
   readonly bundle?: boolean;
   readonly bundleId?: string;
+  /**
+   * Windows only: link as a console-subsystem executable instead of the default
+   * Windows subsystem. A GUI program defaults to the Windows subsystem so that
+   * launching it does not open a console window — which also means stdout and
+   * stderr go nowhere, so set this while debugging a GUI program.
+   */
+  readonly console?: boolean;
 }
 
 /** The on-disk schema of `xbintsc.config.json`. Every field is optional. */

package/src/driver/win-entry.ts

@@ -0,0 +1,59 @@
+/**
+ * Windows GUI-subsystem entry point.
+ *
+ * A program that links with the `gui` extension is built as a **Windows
+ * subsystem** executable (`/SUBSYSTEM:WINDOWS`), which is what keeps a console
+ * window from flashing up when it is launched. The MSVC C runtime then expects
+ * `WinMain` instead of `main`, and xbintsc's runtime always emits a C `main`
+ * (the program body plus teardown), so the driver links this tiny shim to
+ * bridge the two.
+ *
+ * It is compiled on demand and cached like the icon object; nothing here is
+ * platform-abstract — on every other platform the file is never used.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { hashParts } from "./cache.js";
+import { compileC, type Runner } from "./toolchain.js";
+
+/** The bridge source. `main` is the entry point the runtime emits. */
+export const WINDOWS_ENTRY_SOURCE = `/* Generated by xbintsc - Windows GUI subsystem entry point. Do not edit. */
+#ifndef UNICODE
+#define UNICODE
+#endif
+#include <windows.h>
+
+/* The xbintsc runtime defines the C program entry point; hand it the command
+ * line minus the argv[0] hole so it still sees its own arguments. */
+int main(int argc, char **argv);
+
+int WINAPI WinMain(HINSTANCE instance, HINSTANCE previous, LPSTR command_line, int show) {
+  (void)instance;
+  (void)previous;
+  (void)command_line;
+  (void)show;
+  return main(__argc, __argv);
+}
+`;
+
+/**
+ * Compile the entry shim into an object file (cached by source + platform +
+ * toolchain) and return its path.
+ */
+export function ensureWindowsEntryObject(
+  runner: Runner,
+  clang: string,
+  cacheDir: string,
+  env?: Record<string, string>,
+): string {
+  const key = hashParts(["win-gui-entry", process.platform, clang, WINDOWS_ENTRY_SOURCE]);
+  const sourcePath = join(cacheDir, `winentry-${key}.c`);
+  const objectPath = join(cacheDir, `winentry-${key}.o`);
+  if (!existsSync(objectPath)) {
+    mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(sourcePath, WINDOWS_ENTRY_SOURCE);
+    compileC(runner, clang, sourcePath, objectPath, cacheDir, env);
+  }
+  return objectPath;
+}