@gtkx/codegen 1.1.0 → 1.2.0

package/src/compile.ts

@@ -1,4 +1,4 @@
-import { errorMessage, normalizeError } from "@gtkx/utils";
+import { errorCode, errorMessage, normalizeError } from "@gtkx/utils";
 import { existsSync, mkdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,10 +14,19 @@ type SourceModule = ProjectFile & {
     source: string;
 };
 
-type CompileProjectParams = {
+type ProjectContext = {
     projectDir: string;
     files: ProjectFile[];
+    label: string;
+};
+
+type CompileProjectParams = ProjectContext & {
     compilerOptions: Record<string, unknown>;
+};
+
+type EmitModulesParams = {
+    projectDir: string;
+    files: SourceModule[];
     label: string;
 };
 
@@ -60,9 +69,33 @@ const CHECK_OPTIONS = {
     noEmit: true,
 };
 
+const DECLARATION_EMIT = {
+    declaration: true,
+    isolatedDeclarations: true,
+    removeComments: false,
+};
+
+const MODULE_EMIT = {
+    removeComments: false,
+};
+
+const DECLARATION_OPTIONS = ts.convertCompilerOptionsFromJson(
+    { ...BASE_COMPILER_OPTIONS, ...DECLARATION_EMIT },
+    ".",
+).options;
+
+const MODULE_OPTIONS = ts.convertCompilerOptionsFromJson(
+    { ...BASE_COMPILER_OPTIONS, ...MODULE_EMIT },
+    ".",
+).options;
+
+const TS_EXTENSION_PATTERN = /\.tsx?$/;
+const DECLARATION_EXTENSION = ".d.ts";
+const JAVASCRIPT_EXTENSION = ".js";
 const CHECK_DIR = ".gtkx-check";
 const FAILED_CHECK_DIR = `${CHECK_DIR}.failed`;
 const LEGACY_CHECK_PREFIX = `${CHECK_DIR}-`;
+const ESM_SCOPE_MANIFEST = `${JSON.stringify({ type: "module" }, null, 4)}\n`;
 
 const FORMAT_HOST: ts.FormatDiagnosticsHost = {
     getCanonicalFileName: (fileName) => fileName,
@@ -90,6 +123,16 @@ const linkToolingModules = (projectDir: string): (() => void) => {
     };
 };
 
+const ensureModuleScope = (projectDir: string): void => {
+    try {
+        writeFileSync(join(projectDir, "package.json"), ESM_SCOPE_MANIFEST, { flag: "wx" });
+    } catch (error) {
+        if (errorCode(error) !== "EEXIST") {
+            throw error;
+        }
+    }
+};
+
 const isProjectFile = (rel: string): boolean =>
     !rel.startsWith("..") && !isAbsolute(rel) && !rel.split(/[/\\]/).includes("node_modules");
 
@@ -160,17 +203,17 @@ const originLines = (diagnosed: DiagnosedFile[], files: ProjectFile[]): string[]
         ([origin, generated]) => `Generated from ${origin}: ${[...generated].join(", ")}`,
     );
 
-const diagnosticError = (params: CompileProjectParams, diagnostics: ts.Diagnostic[]): Error => {
+const diagnosticError = (params: ProjectContext, diagnostics: ts.Diagnostic[]): Error => {
     const diagnosed = projectDiagnosticFiles(diagnostics, params.projectDir);
     const { label } = params;
 
     if (diagnosed.length === 0) {
-        return new Error(`Type checking ${label} failed:\n${ts.formatDiagnostics(diagnostics, FORMAT_HOST).trim()}`);
+        return new Error(`Compiling ${label} failed:\n${ts.formatDiagnostics(diagnostics, FORMAT_HOST).trim()}`);
     }
 
     const lines = [...diagnosed.map((entry) => entry.text), ...originLines(diagnosed, params.files)];
 
-    return new Error(`Type checking ${label} found ${String(diagnosed.length)} error(s):\n${lines.join("\n")}`);
+    return new Error(`Compiling ${label} found ${String(diagnosed.length)} error(s):\n${lines.join("\n")}`);
 };
 
 const keepFailedProject = (input: FailedProjectInput): Error => {
@@ -214,7 +257,45 @@ const runProgram = (params: CompileProjectParams): ts.Diagnostic[] => {
     return [...program.emit().diagnostics];
 };
 
+const replaceExtension = (fileName: string, extension: string): string =>
+    `${fileName.replace(TS_EXTENSION_PATTERN, "")}${extension}`;
+
+const transpileOptions = (compilerOptions: ts.CompilerOptions, fileName: string): ts.TranspileOptions => ({
+    compilerOptions,
+    fileName,
+    reportDiagnostics: true,
+});
+
+const emitModule = (module: SourceModule, projectDir: string): ts.Diagnostic[] => {
+    const fileName = join(projectDir, module.fileName);
+    const declaration = ts.transpileDeclaration(module.source, transpileOptions(DECLARATION_OPTIONS, fileName));
+    const javascript = ts.transpileModule(module.source, transpileOptions(MODULE_OPTIONS, fileName));
+    const diagnostics = [...declaration.diagnostics ?? [], ...javascript.diagnostics ?? []];
+
+    if (diagnostics.length > 0) {
+        return diagnostics;
+    }
+
+    writeFileSync(replaceExtension(fileName, DECLARATION_EXTENSION), declaration.outputText);
+    writeFileSync(replaceExtension(fileName, JAVASCRIPT_EXTENSION), javascript.outputText);
+
+    return [];
+};
+
+const emitModules = (params: EmitModulesParams): void => {
+    const diagnostics: ts.Diagnostic[] = [];
+
+    for (const module of params.files) {
+        diagnostics.push(...emitModule(module, params.projectDir));
+    }
+
+    if (diagnostics.length > 0) {
+        throw diagnosticError(params, diagnostics);
+    }
+};
+
 const compileProject = (params: CompileProjectParams): void => {
+    ensureModuleScope(params.projectDir);
     const unlinkToolingModules = linkToolingModules(params.projectDir);
 
     try {
@@ -261,4 +342,4 @@ const checkModules = (params: { modules: SourceModule[]; resolveFrom: string; la
     rmSync(keepAt, { recursive: true, force: true });
 };
 
-export { compileProject, checkModules, keepFailedProject, type ProjectFile, type SourceModule };
+export { checkModules, emitModules, keepFailedProject, type SourceModule };

package/src/docs/api-reference.ts

@@ -24,6 +24,8 @@ type ApiReferenceOptions = {
     props?: ElementProps;
     /** GObject properties the project omits from generated props; without it pages show props that do not exist. */
     omittedProps?: OmittedProps;
+    /** Describes GIR byte sequences as `Uint8Array` rather than `number[]`; defaults to false. */
+    isByteArrayTyped?: boolean;
 };
 
 /** Narrows an `ApiReference.symbols` enumeration. */
@@ -371,7 +373,7 @@ class ApiReference {
         this.libraries = options.libraries;
         this.props = options.props ?? {};
         this.omittedProps = options.omittedProps ?? {};
-        this.library = Library.load(options.libraries, options.girPath);
+        this.library = Library.load(options.libraries, options.girPath, options.isByteArrayTyped === true);
         this.elementContext = { library: this.library, linkFor: (): string | undefined => undefined };
         this.buildIndex();
     }

package/src/docs/pipeline.ts

@@ -5,6 +5,7 @@ import {
     computeDocsFingerprint,
     type DocsFingerprintInput,
     FINGERPRINT_FILENAME,
+    type GiInputs,
     isDocsOutputFresh,
 } from "../fingerprint.js";
 import { Library } from "../gir/library.js";
@@ -37,6 +38,7 @@ type DocsOptions = {
     props?: ElementProps;
     omittedProps?: OmittedProps;
     isForced?: boolean;
+    isByteArrayTyped?: boolean;
 };
 
 type DocsManifest = {
@@ -253,6 +255,13 @@ const outDirRefusal = (outDir: string, reason: string): Error =>
         "empty directory or at one gtkx generated, or remove it yourself first.",
     );
 
+const giInputs = (options: DocsOptions, girFiles: string[]): GiInputs => ({
+    girFiles,
+    libraries: options.libraries,
+    girPath: options.girPath,
+    isByteArrayTyped: options.isByteArrayTyped === true,
+});
+
 const assertOwnedOutDir = (options: DocsOptions, manifest: DocsManifest | undefined): void => {
     const stats = statSync(options.outDir, { throwIfNoEntry: false });
 
@@ -301,7 +310,7 @@ const cachedDocsResult = (
         return undefined;
     }
 
-    if (!isDocsOutputFresh(options.outDir, options.libraries, options.girPath, input)) {
+    if (!isDocsOutputFresh(options.outDir, giInputs(options, []), input)) {
         return undefined;
     }
 
@@ -335,18 +344,15 @@ const writeDocs = (options: DocsOptions): DocsResult => {
     }
 
     assertOwnedOutDir(options, previous);
-    const library = Library.load(options.libraries, options.girPath);
+    const library = Library.load(options.libraries, options.girPath, options.isByteArrayTyped === true);
     const { pages, namespaces } = generatePages(options, input.basePath, library);
     clearOutDir(options, previous);
     mkdirSync(options.outDir, { recursive: true });
     const manifest: DocsManifest = { generator: MANIFEST_GENERATOR, namespaces };
     writeFileSync(manifestPath, JSON.stringify(manifest));
     writePages(options.outDir, pages);
-
-    writeFileSync(
-        join(options.outDir, FINGERPRINT_FILENAME),
-        JSON.stringify(computeDocsFingerprint(library.girFiles, options.libraries, options.girPath, input)),
-    );
+    const fingerprint = computeDocsFingerprint(giInputs(options, library.girFiles), input);
+    writeFileSync(join(options.outDir, FINGERPRINT_FILENAME), JSON.stringify(fingerprint));
 
     return { isRegenerated: true, namespaces };
 };

package/src/docs/symbol-page.ts

@@ -16,7 +16,6 @@ import { PRIMITIVE_TS_TYPE, primitiveCategory } from "../gir/primitives.js";
 import { callableSpec } from "../store/gi/callable-doc.js";
 import {
     dedupeCallables,
-    indexMethodsByName,
     instanceScope,
     matchStaticFinishFunction,
     renderInstanceMethodSignature,
@@ -146,7 +145,6 @@ type MemberOwner = {
 type PropertyAccessorSetup = {
     context: ModuleContext;
     claimedNames: Set<string>;
-    methodByName: Map<string, GirFunction>;
 };
 
 type ResolvedRecordField = NonNullable<ReturnType<typeof resolveRecordFieldEntry>>;
@@ -391,7 +389,6 @@ const propertyAccessorSetup = (
     return {
         context: docsSignatureContext(owner.namespace, library),
         claimedNames,
-        methodByName: indexMethodsByName(dedupeCallables(owner.klass.methods)),
     };
 };
 
@@ -418,7 +415,6 @@ const ownerPropertyEntries = (owner: MemberOwner, setup: PropertyAccessorSetup,
             context: setup.context,
             property,
             claimedNames: setup.claimedNames,
-            methodByName: setup.methodByName,
         });
 
         if (accessor === undefined || seen.has(accessor.jsName)) {

package/src/fingerprint.ts

@@ -7,6 +7,13 @@ import packageManifest from "../package.json" with { type: "json" };
 import { arrayGuard, hasFields, isNumber, isString, optionalGuard } from "./guards.js";
 import { readJsonFile } from "./json.js";
 
+type GiInputs = {
+    girFiles: string[];
+    libraries: string[];
+    girPath: string[];
+    isByteArrayTyped: boolean;
+};
+
 type GiFingerprint = {
     value: string;
     girFiles: string[];
@@ -56,15 +63,17 @@ const overrideFiles = (): string[] => {
         .map((entry: Dirent) => join(entry.parentPath, entry.name));
 };
 
-const hashGi = (girFiles: string[], libraries: string[], girPath: string[]): string => {
+const hashGi = (inputs: GiInputs): string => {
     const hash = createHash("sha256");
     hash.update(CODEGEN_VERSION);
     hash.update("\n");
-    hash.update(sortAlpha(libraries));
+    hash.update(sortAlpha(inputs.libraries));
+    hash.update("\n");
+    hash.update(sortAlpha(inputs.girPath));
     hash.update("\n");
-    hash.update(sortAlpha(girPath));
+    hash.update(String(inputs.isByteArrayTyped));
     hash.update("\n");
-    const hashedFiles = sortStrings([...girFiles, ...overrideFiles()]);
+    const hashedFiles = sortStrings([...inputs.girFiles, ...overrideFiles()]);
 
     for (const file of hashedFiles) {
         hash.update("\n");
@@ -76,15 +85,11 @@ const hashGi = (girFiles: string[], libraries: string[], girPath: string[]): str
     return hash.digest("hex");
 };
 
-const computeGiFingerprint = (
-    girFiles: string[],
-    libraries: string[],
-    girPath: string[],
-): GiFingerprint => ({
-    value: hashGi(girFiles, libraries, girPath),
-    girFiles,
-    libraries,
-    girPath,
+const computeGiFingerprint = (inputs: GiInputs): GiFingerprint => ({
+    value: hashGi(inputs),
+    girFiles: inputs.girFiles,
+    libraries: inputs.libraries,
+    girPath: inputs.girPath,
 });
 
 const readSentinel = (storeDir: string): unknown => readJsonFile(join(storeDir, FINGERPRINT_FILENAME));
@@ -103,30 +108,27 @@ const isDocsFingerprint = (value: unknown): value is DocsFingerprint =>
 const isJsxFingerprint = (value: unknown): value is JsxFingerprint =>
     hasFields<JsxFingerprint>(value, { value: isString, intrinsicElementCount: isNumber });
 
-const recordedGiValue = (sentinel: GiFingerprint, libraries: string[], girPath: string[]): string | undefined => {
-    if (!hasMatchingRecordedInputs(sentinel, libraries, girPath)) {
+const recordedGiValue = (sentinel: GiFingerprint, inputs: GiInputs): string | undefined => {
+    if (!hasMatchingRecordedInputs(sentinel, inputs)) {
         return undefined;
     }
 
     try {
-        return hashGi(sentinel.girFiles, sentinel.libraries, girPath);
+        return hashGi({ ...inputs, girFiles: sentinel.girFiles, libraries: sentinel.libraries });
     } catch {
         return undefined;
     }
 };
 
-const isGiStoreFresh = (
-    giStoreDir: string,
-    libraries: string[],
-    girPath: string[],
-): boolean => {
+const isGiStoreFresh = (giStoreDir: string, inputs: GiInputs): boolean => {
     const sentinel = readSentinel(giStoreDir);
 
-    return isGiFingerprint(sentinel) && recordedGiValue(sentinel, libraries, girPath) === sentinel.value;
+    return isGiFingerprint(sentinel) && recordedGiValue(sentinel, inputs) === sentinel.value;
 };
 
-const hasMatchingRecordedInputs = (sentinel: GiFingerprint, libraries: string[], girPath: string[]): boolean =>
-    sortAlpha(sentinel.libraries) === sortAlpha(libraries) && sortAlpha(sentinel.girPath ?? []) === sortAlpha(girPath);
+const hasMatchingRecordedInputs = (sentinel: GiFingerprint, inputs: GiInputs): boolean =>
+    sortAlpha(sentinel.libraries) === sortAlpha(inputs.libraries) &&
+    sortAlpha(sentinel.girPath ?? []) === sortAlpha(inputs.girPath);
 
 const hashDocs = (giValue: string, input: DocsFingerprintInput): string =>
     createHash("sha256")
@@ -140,30 +142,20 @@ const hashDocs = (giValue: string, input: DocsFingerprintInput): string =>
         )
         .digest("hex");
 
-const computeDocsFingerprint = (
-    girFiles: string[],
-    libraries: string[],
-    girPath: string[],
-    input: DocsFingerprintInput,
-): DocsFingerprint => {
-    const gi = computeGiFingerprint(girFiles, libraries, girPath);
+const computeDocsFingerprint = (inputs: GiInputs, input: DocsFingerprintInput): DocsFingerprint => {
+    const gi = computeGiFingerprint(inputs);
 
     return { value: hashDocs(gi.value, input), gi };
 };
 
-const isDocsOutputFresh = (
-    outDir: string,
-    libraries: string[],
-    girPath: string[],
-    input: DocsFingerprintInput,
-): boolean => {
+const isDocsOutputFresh = (outDir: string, inputs: GiInputs, input: DocsFingerprintInput): boolean => {
     const sentinel = readSentinel(outDir);
 
     if (!isDocsFingerprint(sentinel)) {
         return false;
     }
 
-    const giValue = recordedGiValue(sentinel.gi, libraries, girPath);
+    const giValue = recordedGiValue(sentinel.gi, inputs);
 
     return giValue !== undefined && hashDocs(giValue, input) === sentinel.value;
 };
@@ -217,6 +209,7 @@ export {
     computeJsxFingerprint,
     jsxStoreFreshness,
     type DocsFingerprintInput,
+    type GiInputs,
     type GiFingerprint,
     type JsxFingerprintInput,
 };

package/src/gi.ts

@@ -9,10 +9,11 @@ type GiCodegenOptions = {
     gi: StoreOptions;
     libraries: string[];
     girPath: string[];
+    isByteArrayTyped: boolean;
 };
 
 const runGiCodegen = (library: Library, options: GiCodegenOptions): number => {
-    const { gi, libraries, girPath } = options;
+    const { gi, libraries, girPath, isByteArrayTyped } = options;
 
     const namespaces: GiNamespaceInput[] = Array.from(library.namespaces.values(), (namespace) => ({
         directory: namespaceDirectory(namespace),
@@ -20,7 +21,13 @@ const runGiCodegen = (library: Library, options: GiCodegenOptions): number => {
         girFile: namespace.girFile,
     }));
 
-    const fingerprint = computeGiFingerprint(library.girFiles, [...libraries], [...girPath]);
+    const fingerprint = computeGiFingerprint({
+        girFiles: library.girFiles,
+        libraries: [...libraries],
+        girPath: [...girPath],
+        isByteArrayTyped,
+    });
+
     writeGiStore(gi, namespaces, fingerprint);
 
     return library.namespaces.size;

package/src/gir/gir-path.ts

@@ -7,7 +7,7 @@ const SYSTEM_GIR_PATH = "/usr/share/gir-1.0";
 /**
  * The directories to search for `.gir` files, in precedence order: the config's own `girPath`, then
  * `GTKX_GIR_PATH`, then `/usr/share/gir-1.0`, then the girdir pkg-config reports for
- * gobject-introspection-1.0. Duplicates are dropped, and the last two are included only when they exist.
+ * gobject-introspection-1.0. Duplicates are dropped, and the system directories are included only when they exist.
  *
  * @throws If pkg-config is installed but fails while being queried.
  */

package/src/gir/library.ts

@@ -84,10 +84,12 @@ class Library {
      *
      * @param libraries GIR identifiers to load, such as `Gtk-4.0`.
      * @param girPath Directories searched, in order, for each `.gir` file.
+     * @param isByteArrayTyped Whether byte sequences render as `Uint8Array` rather than `number[]`.
      * @returns A library holding every namespace that was parsed.
      */
-    static load(libraries: string[], girPath: string[]): Library {
+    static load(libraries: string[], girPath: string[], isByteArrayTyped = false): Library {
         const library = new Library();
+        library.isByteArrayTypedValue = isByteArrayTyped;
         this.drive(library, libraries, girPath);
 
         return library;
@@ -99,6 +101,7 @@ class Library {
     private nsIdByName: Map<string, number> = new Map();
     private typeTables: TypeTable[] = [];
     private girFilesValue: string[] = [];
+    private isByteArrayTypedValue = false;
 
     /** Creates a library with no namespaces loaded; {@link Library.load} builds a populated one. */
     constructor() {
@@ -328,6 +331,11 @@ class Library {
         return this.namespacesByName;
     }
 
+    /** Whether byte sequences render as `Uint8Array` rather than `number[]`. */
+    public get isByteArrayTyped(): boolean {
+        return this.isByteArrayTypedValue;
+    }
+
     /** Paths of the `.gir` files that were read, in the order they were discovered. */
     public get girFiles(): string[] {
         return this.girFilesValue;

package/src/gir/parse.ts

@@ -5,6 +5,11 @@ type RawNode = Record<string, unknown>;
 
 const GIR_LABEL = "GIR file";
 
+const GIR_MALFORMED_REMEDY =
+    "No XML parser can read this file, so report it to whoever ships it. To get past it now, name the " +
+    "libraries you need explicitly in `libraries` and leave this one out, or put a corrected copy of the " +
+    "file in a directory listed in `girPath`, which is searched ahead of the system location.";
+
 const MULTI_TAGS: Set<string> = new Set([
     "include",
     "class",
@@ -44,7 +49,7 @@ function renameReservedTag(tag: string): string {
 }
 
 const parseGirFile = (path: string): RawNode =>
-    parseXmlFile({ parser: PARSER, label: GIR_LABEL, path }) as RawNode;
+    parseXmlFile({ parser: PARSER, label: GIR_LABEL, path, malformedRemedy: GIR_MALFORMED_REMEDY }) as RawNode;
 
 const attr = (node: RawNode | undefined, name: string): string | undefined => {
     if (node === undefined) {

package/src/gir/primitives.ts

@@ -110,7 +110,7 @@ const PRIMITIVE_TS_TYPE: Record<PrimitiveCategory, string> = {
     float64: "number",
     string: "string",
     unichar: "string",
-    pointer: "number",
+    pointer: "bigint",
 };
 
 const primitiveCategory = (name: string): PrimitiveCategory | undefined => PRIMITIVE_BY_NAME.get(name);

package/src/khronos/args.ts

@@ -2,6 +2,7 @@ import { toCamelIdentifier } from "@gtkx/utils";
 import type { GlCommand, GlParam } from "./model.js";
 import type { CommandPlan, GlScalar, ParamPlan, ReturnPlan } from "./plan.js";
 import {
+    type ArrayLayout,
     tArray,
     tBoolean,
     tBuffer,
@@ -50,6 +51,7 @@ type BuildArgOptions = {
 };
 
 const OUT_PLAN_KINDS: Set<string> = new Set(["ref-out", "ref-array-out", "ref-fixed-out", "string-out"]);
+const NUMERIC_LAYOUT: ArrayLayout = { isBytes: false };
 
 const scalarAliasOrGroup = (scalar: GlScalar, group: string | undefined): string =>
     group !== undefined && scalar.isGroupBearing === true ? group : scalar.tsAlias;
@@ -122,12 +124,13 @@ const buildInArg = (options: BuildArgOptions, name: string, track: (alias: strin
             return inArg(name, "string", tString("borrowed"));
         }
         case "string-array-in": {
-            return inArg(name, "string[]", tArray(tString("borrowed")));
+            return inArg(name, "string[]", tArray(tString("borrowed"), undefined, NUMERIC_LAYOUT));
         }
         case "array-in": {
             track(scalarAliasOrGroup(plan.scalar, param.group));
+            const descriptor = tArray(plan.scalar.descriptor, undefined, NUMERIC_LAYOUT);
 
-            return inArg(name, arrayInTsType(plan.scalar, param.group), tArray(plan.scalar.descriptor));
+            return inArg(name, arrayInTsType(plan.scalar, param.group), descriptor);
         }
         case "buffer": {
             return inArg(name, `ArrayBufferView | ${track("GLintptr")} | null`, tBuffer);
@@ -136,7 +139,7 @@ const buildInArg = (options: BuildArgOptions, name: string, track: (alias: strin
             return inArg(name, track("GLintptr"), tUint64);
         }
         case "byte-offset-array": {
-            return inArg(name, `${track("GLintptr")}[]`, tArray(tUint64));
+            return inArg(name, `${track("GLintptr")}[]`, tArray(tUint64, undefined, NUMERIC_LAYOUT));
         }
         case "ref-array-out":
         case "ref-fixed-out":
@@ -165,14 +168,14 @@ const outArgFields = (options: OutArgFieldsOptions): OutArgFields => {
             return {
                 seed: `const ${cellName} = { value: new Array<number>(${lenIdentifier}).fill(0) };`,
                 tsType: `${track(scalarAliasOrGroup(plan.scalar, param.group))}[]`,
-                descriptor: tRef(tSizedArray(plan.scalar.descriptor, sizeIndex)),
+                descriptor: tRef(tSizedArray(plan.scalar.descriptor, sizeIndex, undefined, NUMERIC_LAYOUT)),
             };
         }
         case "ref-fixed-out": {
             return {
                 seed: `const ${cellName} = { value: new Array<number>(${String(plan.length)}).fill(0) };`,
                 tsType: `${track(plan.scalar.tsAlias)}[]`,
-                descriptor: tRef(tFixedArray(plan.scalar.descriptor, plan.length)),
+                descriptor: tRef(tFixedArray(plan.scalar.descriptor, plan.length, undefined, NUMERIC_LAYOUT)),
             };
         }
         case "string-out": {
@@ -204,7 +207,7 @@ const buildOutArg = (options: BuildArgOptions, track: (alias: string) => string)
         throw new Error(`Parameter index ${String(index)} out of range on ${command.name}`);
     }
 
-    const cellName = `out${String(outIndex)}`;
+    const cellName = `__out${String(outIndex)}`;
     const cell: OutArgCell = { isOut: true, cellName, paramIndex: index };
 
     return { ...cell, ...outArgFields({ command, plan, param, cellName, track }) };

package/src/khronos/render.ts

@@ -114,7 +114,7 @@ const returnStatements = (call: string, returned: EmittedReturn, outs: OutArg[])
         return [`${call};`, tail];
     }
 
-    return [`const result = ${call};`, `return [${returned.expr("result")}, ${outValues.join(", ")}];`];
+    return [`const __result = ${call};`, `return [${returned.expr("__result")}, ${outValues.join(", ")}];`];
 };
 
 const renderCommand = (
@@ -135,7 +135,7 @@ const renderCommand = (
     const seeds = outs.map((out) => out.seed);
     const bindExpression = glBind(command.name, descriptors, returned.descriptor);
     const isInline = plan.params.some((paramPlan) => paramPlan.kind === "string-out");
-    const bindingName = isInline ? "binding" : toCamelIdentifier(command.name);
+    const bindingName = isInline ? "__binding" : toCamelIdentifier(command.name);
 
     const body = [
         ...seeds,
@@ -252,12 +252,14 @@ const deriveGenSingular = (
     const descriptors = [...prefix.map((arg) => arg.descriptor), countScalar.descriptor, tRef(outScalar.descriptor)];
     usedTypes.add(outScalar.tsAlias);
     const signature = prefix.map((arg) => `${arg.name}: ${arg.tsType}`).join(", ");
-    const callArgs = [...prefix.map((arg) => arg.name), "1", "out"].join(", ");
+    const callArgs = [...prefix.map((arg) => arg.name), "1", "__out"].join(", ");
     const jsDoc = genSingularJsDoc({ plan, provenance, docs }, prefix, shape);
 
-    const body = ["    const out = { value: 0 };", `    ${bindingName}(${callArgs});`, "    return out.value;"].join(
-        "\n",
-    );
+    const body = [
+        "    const __out = { value: 0 };",
+        `    ${bindingName}(${callArgs});`,
+        "    return __out.value;",
+    ].join("\n");
 
     const binding = glBind(plan.command.name, renderDescriptorList(descriptors), tVoid);
 

package/src/runner.ts

@@ -39,6 +39,8 @@ type CodegenRunnerOptions = {
     userOmittedProps?: OmittedProps;
     /** Regenerates both stores even when their fingerprints are fresh. */
     isForced?: boolean;
+    /** Emits GIR byte sequences as `Uint8Array` rather than `number[]`; defaults to false. */
+    isByteArrayTyped?: boolean;
 };
 
 /** What a `runCodegen` run produced. */
@@ -157,12 +159,14 @@ const emitStoresWithConfig = async (config: {
     girPath: string[];
 }): Promise<StoreResult> => {
     const { options, gi, jsx, libraries, girPath } = config;
+    const isByteArrayTyped = options.isByteArrayTyped === true;
     let library: Library | undefined;
-    const loadLibrary = (): Library => (library ??= Library.load(libraries, girPath));
-    const isGiRegenerated = options.isForced === true || !isGiStoreFresh(gi.storeDir, libraries, girPath);
+    const loadLibrary = (): Library => (library ??= Library.load(libraries, girPath, isByteArrayTyped));
+    const giInputs = { girFiles: [] as string[], libraries, girPath, isByteArrayTyped };
+    const isGiRegenerated = options.isForced === true || !isGiStoreFresh(gi.storeDir, giInputs);
 
     const namespaces = isGiRegenerated
-        ? runGiCodegen(loadLibrary(), { gi, libraries, girPath })
+        ? runGiCodegen(loadLibrary(), { gi, libraries, girPath, isByteArrayTyped })
         : 0;
 
     if (jsx === undefined) {

package/src/staging.ts

@@ -1,12 +1,10 @@
+import { errorCode } from "@gtkx/utils";
 import { mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
 const STAGING_SUFFIX = ".tmp-";
 const OWNER_PATTERN = /^(?<pid>\d+)-/;
 
-const errorCode = (error: unknown): string | undefined =>
-    error instanceof Error && "code" in error && typeof error.code === "string" ? error.code : undefined;
-
 const isOwnerRunning = (pid: number): boolean => {
     if (!Number.isSafeInteger(pid) || pid <= 0) {
         return false;