xbintsc 0.5.32 → 0.5.37

package/README.md

@@ -172,9 +172,11 @@ npx xbintsc doctor
 npx xbintsc build src/main.ts --out build
 ```
 
-It needs Node.js 22+ and a clang 16+ toolchain. The npm package compiles the C
-runtime from source on the first build (later builds reuse `.xbintsc/`), and it
-does not include the GUI/media archives. See
+It needs Node.js 22+ and a clang 16+ toolchain. The install also brings the
+matching `@xbintsc/<os>-<arch>` package with prebuilt runtime archives (`core`,
+`ext_node`, and `gui`/`media` where the release builds them), so the first build
+links them instead of compiling C. If npm skips that optional package, the
+runtime is compiled from the shipped sources and cached in `.xbintsc/`. See
 [Using xbintsc from npm](./doc/npm-package.md) for a complete guide, CI setup
 and caveats.
 
@@ -288,7 +290,7 @@ run();                          // main loop, until every window closes
 npm run gui
 npx tsx src/cli/main.ts run examples/gui/hello.ts --ext gui
 
-# A prebuilt Linux/macOS release archive already ships the engine:
+# A release archive or an npm install already ships the engine:
 xbintsc run app.ts --ext gui
 
 # <video>/<audio> playback is a separate opt-in archive, so GUI-only binaries
@@ -314,9 +316,10 @@ whose document also opens unchanged in a browser.
 Platforms and full details: [doc/gui.md](./doc/gui.md) is the engine overview
 (architecture and roadmap); the per-function documents live under
 [doc/gui/](./doc/gui) — API, DOM/CSS, layout, rendering, media, input, animation,
-runtime, build and known issues. Linux and macOS are built and exercised in CI
-and their release archives ship the engine (`gui.a`) plus the optional media
-archive (`media.a`). Windows x64 gets the same pair (`gui.lib` through SDL_GPU's
+runtime, build and known issues. Linux and macOS are built and exercised in CI;
+their release archives and the optional `@xbintsc/<os>-<arch>` npm packages ship
+the engine (`gui.a`) plus the optional media archive (`media.a`). Windows x64
+gets the same pair (`gui.lib` through SDL_GPU's
 Vulkan backend, and `media.lib` from FFmpeg compiled with clang-cl for the MSVC
 ABI), built in CI with the Visual Studio MSVC + LLVM toolchain a local build
 uses; Windows arm64 still skips them. Running the examples in CI stays

package/README.zh-CN.md

@@ -153,9 +153,11 @@ npx xbintsc doctor
 npx xbintsc build src/main.ts --out build
 ```
 
-它需要 Node.js 22+ 与 clang 16+ 工具链。npm 包在首次构建时会从源码编译 C 运行时
-（后续构建复用 `.xbintsc/`），并且不包含 GUI/media 归档。完整指南、CI 配置与注意
-事项见[通过 npm 包使用 xbintsc](./doc/zh-CN/npm-package.md)。
+它需要 Node.js 22+ 与 clang 16+ 工具链。安装时还会带上宿主平台对应的
+`@xbintsc/<os>-<arch>` 包，其中包含预编译运行时归档（`core`、`ext_node`，以及
+发布为其构建的 `gui`/`media`），所以首次构建直接链接归档而不编译 C。如果 npm
+跳过了这个可选包，才会从随包源码编译运行时并缓存到 `.xbintsc/`。完整指南、CI
+配置与注意事项见[通过 npm 包使用 xbintsc](./doc/zh-CN/npm-package.md)。
 
 ### 作为开发者（从源码）
 
@@ -233,7 +235,7 @@ run();                          // 主循环，直到所有窗口关闭
 npm run gui
 npx tsx src/cli/main.ts run examples/gui/hello.ts --ext gui
 
-# 预编译的 Linux/macOS 发布包已经内含该引擎：
+# 发布包或 npm 安装都已经内含该引擎：
 xbintsc run app.ts --ext gui
 
 # <video>/<audio> 播放是单独的可选归档，因此只做界面的二进制不会链接 FFmpeg：
@@ -256,10 +258,10 @@ xbintsc run examples/gui/media.ts --ext gui,media
 平台与完整说明：[doc/zh-CN/gui.md](./doc/zh-CN/gui.md) 是引擎总览（架构与
 路线图）；按功能拆分的文档位于 [doc/zh-CN/gui/](./doc/zh-CN/gui) —— API、
 DOM/CSS、布局、绘制、媒体、输入、动画、运行时、构建与已知问题。Linux 与 macOS 已在 CI 中构建
-并实际运行，其发布包内含引擎（`gui.a`）与可选的媒体归档（`media.a`）；Windows 的
-`gui.lib`（通过 SDL_GPU 的 Vulkan 后端渲染）由同一脚本产出，但仍是暂定状态，尚未
-随发布包提供。媒体播放目前仅支持 POSIX：没有 `media.a` 或在 Windows 上，
-`<video>` 与 `<audio>` 会触发 `error`。
+并实际运行，其发布包与可选的 `@xbintsc/<os>-<arch>` npm 包内含引擎（`gui.a`）与
+可选的媒体归档（`media.a`）；Windows x64 也会随发布包与 npm 平台包提供 `gui.lib`
+（通过 SDL_GPU 的 Vulkan 后端渲染）与 `media.lib`。媒体播放目前仅支持 POSIX：没有
+`media.a` 或在 Windows 上，`<video>` 与 `<audio>` 会触发 `error`。
 
 ## 增量编译
 

package/dist/scripts/check-version.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * Verify the release bookkeeping that must agree before a tag is pushed:
+ *
+ *   1. `COMPILER_VERSION` (reported by `xbintsc version` / `doctor` and embedded
+ *      in the incremental cache key) matches the version in `package.json`;
+ *   2. every `@xbintsc/<os>-<arch>` optional dependency is either the current
+ *      version (a release checkout) or the published `0.0.0` placeholder (the
+ *      committed state; release automation rewrites it before `npm publish`).
+ *
+ * A mismatch means an upgraded compiler can reuse binaries produced by the
+ * previous one while presenting the wrong version to bug reports, or that an
+ * install would ask npm for a platform package that does not exist.
+ */
+/** The version of the empty `@xbintsc/*` packages created before a release. */
+export declare const PLATFORM_PLACEHOLDER_VERSION = "0.0.0";
+/** Read the version literal from the compiler source. */
+export declare function compilerVersionOf(root: string): string;
+/** Read the published version from package.json. */
+export declare function packageVersionOf(root: string): string;
+/** Returns a human-readable mismatch message, or `undefined` when in sync. */
+export declare function checkCompilerVersion(root: string): string | undefined;
+/**
+ * Returns a message when a platform optional dependency names a version that is
+ * neither the release version nor the placeholder, or `undefined` when valid.
+ */
+export declare function checkPlatformVersions(root: string): string | undefined;

package/dist/scripts/check-version.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Verify the release bookkeeping that must agree before a tag is pushed:
+ *
+ *   1. `COMPILER_VERSION` (reported by `xbintsc version` / `doctor` and embedded
+ *      in the incremental cache key) matches the version in `package.json`;
+ *   2. every `@xbintsc/<os>-<arch>` optional dependency is either the current
+ *      version (a release checkout) or the published `0.0.0` placeholder (the
+ *      committed state; release automation rewrites it before `npm publish`).
+ *
+ * A mismatch means an upgraded compiler can reuse binaries produced by the
+ * previous one while presenting the wrong version to bug reports, or that an
+ * install would ask npm for a platform package that does not exist.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+/** The version of the empty `@xbintsc/*` packages created before a release. */
+export const PLATFORM_PLACEHOLDER_VERSION = "0.0.0";
+/** Read the version literal from the compiler source. */
+export function compilerVersionOf(root) {
+    const text = readFileSync(join(root, "src", "driver", "version.ts"), "utf8");
+    const match = /export const COMPILER_VERSION = "([^"]+)"/.exec(text);
+    if (!match)
+        throw new Error("COMPILER_VERSION is not declared in src/driver/version.ts");
+    return match[1];
+}
+/** Read the published version from package.json. */
+export function packageVersionOf(root) {
+    const parsed = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    if (!parsed.version)
+        throw new Error("package.json has no version field");
+    return parsed.version;
+}
+/** Returns a human-readable mismatch message, or `undefined` when in sync. */
+export function checkCompilerVersion(root) {
+    const packageVersion = packageVersionOf(root);
+    const compilerVersion = compilerVersionOf(root);
+    if (packageVersion === compilerVersion)
+        return undefined;
+    return (`COMPILER_VERSION is "${compilerVersion}" but package.json is "${packageVersion}".\n` +
+        'Update COMPILER_VERSION in src/driver/version.ts (it keys the incremental cache), or fix package.json.');
+}
+/**
+ * Returns a message when a platform optional dependency names a version that is
+ * neither the release version nor the placeholder, or `undefined` when valid.
+ */
+export function checkPlatformVersions(root) {
+    const parsed = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    for (const [name, spec] of Object.entries(parsed.optionalDependencies ?? {})) {
+        if (!name.startsWith("@xbintsc/"))
+            continue;
+        if (spec === parsed.version || spec === PLATFORM_PLACEHOLDER_VERSION)
+            continue;
+        return (`optional dependency ${name} is "${spec}", but package.json is "${parsed.version}".\n` +
+            `Use "${PLATFORM_PLACEHOLDER_VERSION}" in the committed manifest (release automation rewrites it) ` +
+            `or "${parsed.version}" in a release checkout.`);
+    }
+    return undefined;
+}
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+    const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+    const problems = [checkCompilerVersion(root), checkPlatformVersions(root)].filter((problem) => problem !== undefined);
+    if (problems.length > 0) {
+        process.stderr.write(`xbintsc: version mismatch\n${problems.join("\n")}\n`);
+        process.exit(1);
+    }
+    process.stdout.write(`xbintsc: version ${compilerVersionOf(root)} matches package.json\n`);
+}
+//# sourceMappingURL=check-version.js.map

package/dist/scripts/check-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-version.js","sourceRoot":"","sources":["../../scripts/check-version.ts"],"names":[],"mappings":"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"}

package/dist/scripts/package-platform.d.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * Assemble the optional `@xbintsc/<os>-<arch>` npm package for the current host.
+ *
+ * The package carries the prebuilt archives in the same layout the compiler
+ * already searches:
+ *
+ *   package/runtime/lib/<os>-<arch>/{core,ext_node}.{a,lib}
+ *   package/runtime/lib/<os>-<arch>/gui.{a,lib}       (when the release ships it)
+ *   package/runtime/lib/<os>-<arch>/media.{a,lib}     (when the release ships it)
+ *
+ * `xbintsc` lists these packages in `optionalDependencies`, so npm installs the
+ * one matching the host and the driver links its archives instead of compiling
+ * the C runtime. Release automation publishes the tarball produced here; see
+ * `.github/workflows/release.yml`.
+ *
+ * Output: `dist/npm-platform/xbintsc-<os>-<arch>-<version>.tgz`.
+ */
+export interface PackageRepository {
+    readonly type: string;
+    readonly url: string;
+}
+export interface PlatformPackageOptions {
+    readonly version: string;
+    readonly slug: string;
+    readonly repository?: PackageRepository;
+}
+export interface PlatformPackageManifest {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly license: string;
+    readonly repository?: PackageRepository;
+    readonly os: readonly string[];
+    readonly cpu: readonly string[];
+    readonly files: readonly string[];
+    readonly publishConfig: {
+        readonly access: "public";
+    };
+}
+/** Every host a release publishes a platform package for. */
+export declare const PLATFORM_SLUGS: readonly ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64", "win32-arm64"];
+/** npm name of the platform package, e.g. `@xbintsc/linux-x64`. */
+export declare function platformPackageName(slug: string): string;
+/**
+ * File name `npm pack` gives the platform package, e.g.
+ * `xbintsc-linux-x64-1.2.3.tgz` (npm drops the scope from the file name).
+ */
+export declare function platformPackageFileName(slug: string, version: string): string;
+/** Archives every platform package must contain. */
+export declare function requiredArchives(slug: string): string[];
+/** The package manifest written into the staging tree and packed by npm. */
+export declare function platformPackageManifest(options: PlatformPackageOptions): PlatformPackageManifest;
+/**
+ * Copy the host's archives into a staging tree, write the manifest and run
+ * `npm pack`. Returns the absolute path of the produced `.tgz`.
+ */
+export declare function packagePlatform(root: string, slug?: string): string;

package/dist/scripts/package-platform.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+/**
+ * Assemble the optional `@xbintsc/<os>-<arch>` npm package for the current host.
+ *
+ * The package carries the prebuilt archives in the same layout the compiler
+ * already searches:
+ *
+ *   package/runtime/lib/<os>-<arch>/{core,ext_node}.{a,lib}
+ *   package/runtime/lib/<os>-<arch>/gui.{a,lib}       (when the release ships it)
+ *   package/runtime/lib/<os>-<arch>/media.{a,lib}     (when the release ships it)
+ *
+ * `xbintsc` lists these packages in `optionalDependencies`, so npm installs the
+ * one matching the host and the driver links its archives instead of compiling
+ * the C runtime. Release automation publishes the tarball produced here; see
+ * `.github/workflows/release.yml`.
+ *
+ * Output: `dist/npm-platform/xbintsc-<os>-<arch>-<version>.tgz`.
+ */
+import { spawnSync } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { platformSlug } from "../src/driver/paths.js";
+/** Every host a release publishes a platform package for. */
+export const PLATFORM_SLUGS = [
+    "linux-x64",
+    "linux-arm64",
+    "darwin-x64",
+    "darwin-arm64",
+    "win32-x64",
+    "win32-arm64",
+];
+/** npm name of the platform package, e.g. `@xbintsc/linux-x64`. */
+export function platformPackageName(slug) {
+    return `@xbintsc/${slug}`;
+}
+/**
+ * File name `npm pack` gives the platform package, e.g.
+ * `xbintsc-linux-x64-1.2.3.tgz` (npm drops the scope from the file name).
+ */
+export function platformPackageFileName(slug, version) {
+    return `xbintsc-${slug}-${version}.tgz`;
+}
+/** Split `linux-x64` into its npm `os` and `cpu` constraints. */
+function splitSlug(slug) {
+    const dash = slug.lastIndexOf("-");
+    if (dash <= 0 || dash === slug.length - 1) {
+        throw new Error(`invalid platform slug "${slug}" (expected <os>-<arch>)`);
+    }
+    return { os: slug.slice(0, dash), arch: slug.slice(dash + 1) };
+}
+/** Archives every platform package must contain. */
+export function requiredArchives(slug) {
+    const suffix = slug.startsWith("win32-") ? ".lib" : ".a";
+    return [`core${suffix}`, `ext_node${suffix}`];
+}
+/** The package manifest written into the staging tree and packed by npm. */
+export function platformPackageManifest(options) {
+    const { os, arch } = splitSlug(options.slug);
+    const name = platformPackageName(options.slug);
+    return {
+        name,
+        version: options.version,
+        description: `Prebuilt xbintsc C runtime archives for ${options.slug}. Installed automatically by xbintsc.`,
+        license: "MIT",
+        ...(options.repository ? { repository: options.repository } : {}),
+        os: [os],
+        cpu: [arch],
+        files: ["runtime"],
+        publishConfig: { access: "public" },
+    };
+}
+/** Run npm through the same CLI that invoked this script, when available. */
+function runNpm(args, cwd) {
+    const execPath = process.env.npm_execpath;
+    const useCli = execPath !== undefined && /\.(cjs|mjs|js)$/.test(execPath);
+    const command = useCli ? process.execPath : process.platform === "win32" ? "npm.cmd" : "npm";
+    const commandArgs = useCli ? [execPath, ...args] : [...args];
+    const result = spawnSync(command, commandArgs, {
+        cwd,
+        encoding: "utf8",
+        shell: !useCli && process.platform === "win32",
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        throw new Error(`npm ${args.join(" ")} failed (${result.status}):\n${result.stderr}`);
+    }
+    return { stdout: result.stdout };
+}
+/**
+ * Copy the host's archives into a staging tree, write the manifest and run
+ * `npm pack`. Returns the absolute path of the produced `.tgz`.
+ */
+export function packagePlatform(root, slug = platformSlug()) {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    const libDir = join(root, "runtime", "lib", slug);
+    const missing = requiredArchives(slug).filter((name) => !existsSync(join(libDir, name)));
+    if (missing.length > 0) {
+        throw new Error(`missing ${missing.join(", ")} in ${libDir}; run \`npm run runtime\` first`);
+    }
+    const stageRoot = join(root, "build", "npm-platform-stage");
+    const stage = join(stageRoot, "package");
+    rmSync(stageRoot, { recursive: true, force: true });
+    mkdirSync(stage, { recursive: true });
+    cpSync(libDir, join(stage, "runtime", "lib", slug), { recursive: true });
+    const manifest = platformPackageManifest({
+        version: pkg.version,
+        slug,
+        ...(pkg.repository ? { repository: pkg.repository } : {}),
+    });
+    writeFileSync(join(stage, "package.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+    writeFileSync(join(stage, "README.md"), `# ${manifest.name}\n\n` +
+        `Prebuilt xbintsc runtime archives for \`${slug}\`.\n\n` +
+        `This package is installed automatically as an optional dependency of\n` +
+        `[\`xbintsc\`](https://www.npmjs.com/package/xbintsc) and is not meant to be\n` +
+        `used on its own. The compiler links \`runtime/lib/${slug}/\` from this\n` +
+        `package instead of compiling its C runtime on the first build.\n`);
+    const license = join(root, "LICENSE");
+    if (existsSync(license))
+        cpSync(license, join(stage, "LICENSE"));
+    const outDir = join(root, "dist", "npm-platform");
+    rmSync(outDir, { recursive: true, force: true });
+    mkdirSync(outDir, { recursive: true });
+    const packed = JSON.parse(runNpm(["pack", "--json", "--pack-destination", outDir], stage).stdout);
+    const filename = packed[0]?.filename;
+    if (!filename)
+        throw new Error("npm pack did not report a tarball name");
+    return join(outDir, filename);
+}
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+    try {
+        const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+        console.log(`xbintsc: wrote ${packagePlatform(root)}`);
+    }
+    catch (error) {
+        console.error(`xbintsc: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=package-platform.js.map

package/dist/scripts/package-platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-platform.js","sourceRoot":"","sources":["../../scripts/package-platform.ts"],"names":[],"mappings":"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"}

package/dist/scripts/verify-platform-package.d.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Verify the `@xbintsc/<os>-<arch>` npm tarballs staged for a release.
+ *
+ * `release.yml` publishes one platform package per host before `xbintsc` and
+ * then points the main manifest's `optionalDependencies` at exactly those
+ * versions, so every tarball has to prove it was packed from this release: its
+ * manifest must name `@xbintsc/<slug>@<version>` and it must carry the runtime
+ * archives the driver links (`core` and `ext_node`, see `requiredArchives`).
+ *
+ * This runs in Node on purpose. The check used to be a shell pipeline,
+ * `tar -tf x.tgz | grep -q <pattern>`, under `set -o pipefail`: `grep -q` closes
+ * the pipe on its first match, so `tar` — still decompressing the tens of
+ * megabytes that follow `core.a` — dies of SIGPIPE, and the pipeline reports a
+ * perfectly good tarball as "has no core runtime archive". Reading the gzip
+ * stream here has no such race, needs no external `tar` and behaves the same on
+ * every host.
+ *
+ * Usage: `npm run verify:platform -- --dir platform-packages [--version x.y.z]`
+ */
+/** One member of a tar archive; `data` is a view into the decompressed stream. */
+export interface TarEntry {
+    readonly path: string;
+    readonly data: Buffer;
+}
+/** List the regular files of a gzip-compressed tar archive, in archive order. */
+export declare function tarballEntries(tgz: Buffer, source?: string): TarEntry[];
+/**
+ * Check one platform tarball's manifest identity and runtime archives.
+ * `source` names the tarball in error messages (its path, or a fixture name).
+ */
+export declare function verifyPlatformEntries(entries: readonly TarEntry[], slug: string, version: string, source?: string): void;
+/** Read `tgzPath` and verify it as the platform package for `slug`/`version`. */
+export declare function verifyPlatformPackage(tgzPath: string, slug: string, version: string): TarEntry[];

package/dist/scripts/verify-platform-package.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * Verify the `@xbintsc/<os>-<arch>` npm tarballs staged for a release.
+ *
+ * `release.yml` publishes one platform package per host before `xbintsc` and
+ * then points the main manifest's `optionalDependencies` at exactly those
+ * versions, so every tarball has to prove it was packed from this release: its
+ * manifest must name `@xbintsc/<slug>@<version>` and it must carry the runtime
+ * archives the driver links (`core` and `ext_node`, see `requiredArchives`).
+ *
+ * This runs in Node on purpose. The check used to be a shell pipeline,
+ * `tar -tf x.tgz | grep -q <pattern>`, under `set -o pipefail`: `grep -q` closes
+ * the pipe on its first match, so `tar` — still decompressing the tens of
+ * megabytes that follow `core.a` — dies of SIGPIPE, and the pipeline reports a
+ * perfectly good tarball as "has no core runtime archive". Reading the gzip
+ * stream here has no such race, needs no external `tar` and behaves the same on
+ * every host.
+ *
+ * Usage: `npm run verify:platform -- --dir platform-packages [--version x.y.z]`
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { gunzipSync } from "node:zlib";
+import { PLATFORM_SLUGS, platformPackageFileName, platformPackageName, requiredArchives, } from "./package-platform.js";
+const BLOCK = 512;
+/** Read a header field, stopping at its NUL padding. */
+function readString(block, offset, length) {
+    const field = block.subarray(offset, offset + length);
+    const end = field.indexOf(0);
+    return field.subarray(0, end === -1 ? field.length : end).toString("utf8");
+}
+/** Decode a numeric header field (octal, or base-256 for very large values). */
+function readNumber(block, offset, length) {
+    if ((block[offset] & 0x80) !== 0) {
+        let value = block[offset] & 0x7f;
+        for (let index = 1; index < length; index += 1)
+            value = value * 256 + block[offset + index];
+        return value;
+    }
+    const text = readString(block, offset, length).trim();
+    return text === "" ? 0 : Number.parseInt(text, 8);
+}
+/** The `path=` record of a pax extended header, when it carries one. */
+function paxPath(data) {
+    // Records are `<byte length> <key>=<value>\n`; only the path matters here.
+    const match = /(?:^|\n)\d+ path=([^\n]*)\n/.exec(data.toString("utf8"));
+    return match?.[1];
+}
+/** List the regular files of a gzip-compressed tar archive, in archive order. */
+export function tarballEntries(tgz, source = "tarball") {
+    let tar;
+    try {
+        tar = gunzipSync(tgz);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`${source} is not a gzip-compressed tar archive (${reason})`);
+    }
+    const entries = [];
+    let offset = 0;
+    let override;
+    while (offset + BLOCK <= tar.length) {
+        const header = tar.subarray(offset, offset + BLOCK);
+        if (header.every((byte) => byte === 0))
+            break;
+        const size = readNumber(header, 124, 12);
+        const type = header[156] === 0 ? "0" : String.fromCharCode(header[156]);
+        const dataStart = offset + BLOCK;
+        if (dataStart + size > tar.length)
+            throw new Error(`${source} is truncated`);
+        const data = tar.subarray(dataStart, dataStart + size);
+        offset = dataStart + Math.ceil(size / BLOCK) * BLOCK;
+        // A long path arrives in its own preceding header: GNU `L` stores it
+        // verbatim, pax `x` records it as `path=`. `K` only renames a link target.
+        if (type === "L") {
+            override = readString(data, 0, data.length);
+            continue;
+        }
+        if (type === "x") {
+            override = paxPath(data) ?? override;
+            continue;
+        }
+        if (type === "K")
+            continue;
+        const prefix = readString(header, 345, 155);
+        const name = readString(header, 0, 100);
+        const path = override ?? (prefix === "" ? name : `${prefix}/${name}`);
+        override = undefined;
+        // Only regular files can be the archives checked below; directories and
+        // links are skipped instead of being reported by their trailing slash.
+        if (type === "0" || type === "7")
+            entries.push({ path, data });
+    }
+    return entries;
+}
+/** Read the manifest out of an already-parsed platform tarball. */
+function manifestOf(entries, source) {
+    const manifest = entries.find((entry) => entry.path === "package/package.json");
+    if (!manifest)
+        throw new Error(`${source} has no package/package.json`);
+    try {
+        return JSON.parse(manifest.data.toString("utf8"));
+    }
+    catch {
+        throw new Error(`${source} has an unreadable package/package.json`);
+    }
+}
+/**
+ * Check one platform tarball's manifest identity and runtime archives.
+ * `source` names the tarball in error messages (its path, or a fixture name).
+ */
+export function verifyPlatformEntries(entries, slug, version, source = "platform package") {
+    const parsed = manifestOf(entries, source);
+    const expectedName = platformPackageName(slug);
+    if (parsed.name !== expectedName || parsed.version !== version) {
+        throw new Error(`${source} contains ${parsed.name}@${parsed.version}, expected ${expectedName}@${version}`);
+    }
+    const paths = new Set(entries.map((entry) => entry.path));
+    for (const archive of requiredArchives(slug)) {
+        const expected = `package/runtime/lib/${slug}/${archive}`;
+        if (paths.has(expected))
+            continue;
+        // Keep the historical wording: `core.a`/`core.lib` is "the core archive".
+        const label = archive.replace(/\.(a|lib)$/, "");
+        throw new Error(`${source} has no ${label} runtime archive (expected ${expected})`);
+    }
+}
+/** Read `tgzPath` and verify it as the platform package for `slug`/`version`. */
+export function verifyPlatformPackage(tgzPath, slug, version) {
+    const entries = tarballEntries(readFileSync(tgzPath), tgzPath);
+    verifyPlatformEntries(entries, slug, version, tgzPath);
+    return entries;
+}
+/** Value of `--name <value>`, or `undefined` when the flag is absent. */
+function argument(name) {
+    const index = process.argv.indexOf(name);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+    try {
+        const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+        const dir = argument("--dir") ?? join(root, "platform-packages");
+        const version = argument("--version") ??
+            JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+        for (const slug of PLATFORM_SLUGS) {
+            const file = join(dir, platformPackageFileName(slug, version));
+            if (!existsSync(file))
+                throw new Error(`Missing npm platform package ${file}.`);
+            const entries = verifyPlatformPackage(file, slug, version);
+            console.log(`xbintsc: ${basename(file)} carries ${entries.length} files`);
+        }
+        console.log(`xbintsc: verified ${PLATFORM_SLUGS.length} platform packages at ${version}`);
+    }
+    catch (error) {
+        console.error(`xbintsc: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=verify-platform-package.js.map

package/dist/scripts/verify-platform-package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-platform-package.js","sourceRoot":"","sources":["../../scripts/verify-platform-package.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/help.d.ts

@@ -4,4 +4,4 @@
  * It lives apart from the command dispatch so the executable entry point stays
  * under the repository's per-file line budget; the text is data, not logic.
  */
-export declare const HELP = "xbintsc 0.5.32 - TypeScript binary compiler\n\nUsage:\n  xbintsc build <file.ts> [options]   Compile to a native binary\n  xbintsc run <file.ts> [-- args]     Compile and execute\n  xbintsc check <file.ts>             Parse, bind and check without linking\n  xbintsc watch <file.ts> [options]   Rebuild whenever the source tree changes\n  xbintsc emit <file.ts>              Print LLVM IR\n  xbintsc doctor                      Report the resolved toolchain\n  xbintsc version                     Print the version\n  xbintsc help                        Show this message\n\nOptions:\n  -o, --output <path>   Output path\n      --out <dir>       Output directory (default: build/)\n      --emit <kind>     exe | obj | ir (default: exe)\n  -O0..-O3              Optimization level (default: -O2)\n      --ext <names>     Comma separated extensions (e.g. node,gui,media)\n      --ext-native <m>  Register a C++/Rust extension from a JSON manifest\n                        (comma separated for several)\n      --config <path>   Use a project config (default: auto-detect\n                        xbintsc.config.json)\n      --no-config       Do not read any project config\n      --icon <path>     Embed an application icon (PNG/ICO/ICNS)\n      --bundle          macOS: also produce a .app bundle\n      --app-name <name> Bundle / display name\n      --app-id <id>     macOS bundle identifier (e.g. com.example.demo)\n      --force           Ignore the incremental cache\n      --verbose         Print progress information\n      --time            Print per-phase build timings\n      --debug           Emit debug info (DWARF/CodeView) and keep frame pointers\n      --check           Run the semantic checker (default)\n      --no-check        Skip the semantic checker; only erase type syntax\n      --lto             Compile program and runtime to LTO bitcode; link with lld\n      --pgo-generate [dir]  Build an instrumented binary writing profiles to dir\n      --pgo-use [dir]   Build with the profiles collected from --pgo-generate\n      --json            Print diagnostics as a JSON array on stdout\n      --no-hints        Do not append the \"hint: \u2026 see <doc>\" line to failures\n\nxbintsc compiles a subset of TypeScript to a native binary. Types are erased;\nonly inference-free facts (names, redeclarations, call arity) are checked.\nNode built-ins need --ext node, packages in node_modules are bundled at build\ntime, and clang 16+ is required to link.\n\nInstalled as a project dependency (npm):\n  npx xbintsc doctor\n  npx xbintsc build <entry.ts> --out build\n  npx xbintsc run <entry.ts>\nThe first build compiles the C runtime; later builds reuse the cache.\n\nDocs: doc/ai/README.md (task guide) - doc/ai/language-support.md (subset) -\ndoc/ai/troubleshooting.md (failures) - llms.txt (index of every document).\nWhen installed from npm, these live under node_modules/xbintsc/doc/ and\nnode_modules/xbintsc/doc/npm-package.md is the project guide.\n";
+export declare const HELP = "xbintsc 0.5.37 - TypeScript binary compiler\n\nUsage:\n  xbintsc build <file.ts> [options]   Compile to a native binary\n  xbintsc run <file.ts> [-- args]     Compile and execute\n  xbintsc check <file.ts>             Parse, bind and check without linking\n  xbintsc watch <file.ts> [options]   Rebuild whenever the source tree changes\n  xbintsc emit <file.ts>              Print LLVM IR\n  xbintsc doctor                      Report the resolved toolchain\n  xbintsc version                     Print the version\n  xbintsc help                        Show this message\n\nOptions:\n  -o, --output <path>   Output path\n      --out <dir>       Output directory (default: build/)\n      --emit <kind>     exe | obj | ir (default: exe)\n  -O0..-O3              Optimization level (default: -O2)\n      --ext <names>     Comma separated extensions (e.g. node,gui,media)\n      --ext-native <m>  Register a C++/Rust extension from a JSON manifest\n                        (comma separated for several)\n      --config <path>   Use a project config (default: auto-detect\n                        xbintsc.config.json)\n      --no-config       Do not read any project config\n      --icon <path>     Embed an application icon (PNG/ICO/ICNS)\n      --bundle          macOS: also produce a .app bundle\n      --app-name <name> Bundle / display name\n      --app-id <id>     macOS bundle identifier (e.g. com.example.demo)\n      --force           Ignore the incremental cache\n      --verbose         Print progress information\n      --time            Print per-phase build timings\n      --debug           Emit debug info (DWARF/CodeView) and keep frame pointers\n      --check           Run the semantic checker (default)\n      --no-check        Skip the semantic checker; only erase type syntax\n      --lto             Compile program and runtime to LTO bitcode; link with lld\n      --pgo-generate [dir]  Build an instrumented binary writing profiles to dir\n      --pgo-use [dir]   Build with the profiles collected from --pgo-generate\n      --json            Print diagnostics as a JSON array on stdout\n      --no-hints        Do not append the \"hint: \u2026 see <doc>\" line to failures\n\nxbintsc compiles a subset of TypeScript to a native binary. Types are erased;\nonly inference-free facts (names, redeclarations, call arity) are checked.\nNode built-ins need --ext node, packages in node_modules are bundled at build\ntime, and clang 16+ is required to link.\n\nInstalled as a project dependency (npm):\n  npx xbintsc doctor\n  npx xbintsc build <entry.ts> --out build\n  npx xbintsc run <entry.ts>\nThe first build compiles the C runtime; later builds reuse the cache.\n\nDocs: doc/ai/README.md (task guide) - doc/ai/language-support.md (subset) -\ndoc/ai/troubleshooting.md (failures) - llms.txt (index of every document).\nWhen installed from npm, these live under node_modules/xbintsc/doc/ and\nnode_modules/xbintsc/doc/npm-package.md is the project guide.\n";