@gtkx/codegen 1.0.0 → 1.2.0

package/src/gir/function.ts

@@ -1,5 +1,6 @@
 import type { GirAnnotations } from "./annotations.js";
 import type { ParseContext } from "./type-id.js";
+import { type CursorParameterNames, PARAMETERS_MISSING_ARRAY_EXTENT } from "./cursor-overrides.js";
 import { PARAMETERS_MISSING_NULLABLE_ANNOTATION } from "./nullable-overrides.js";
 import { type GirParameter, type GirReturnValue, parameterFromNode, parseCallable } from "./parameter.js";
 import { attr, getChild, type RawNode } from "./parse.js";
@@ -50,18 +51,53 @@ const relaxMissingNullable = (fn: GirFunction): GirFunction => {
     return fn;
 };
 
+const parameterIndexFor = (parameters: GirParameter[], name: string): number => {
+    const index = parameters.findIndex((parameter) => parameter.name === name);
+
+    if (index === -1) {
+        throw new Error(`A cursor correction names a parameter the GIR does not declare: ${name}`);
+    }
+
+    return index;
+};
+
+const bindCursorParameters = (parameters: GirParameter[], corrections: CursorParameterNames[]): void => {
+    for (const names of corrections) {
+        const parameter = parameters[parameterIndexFor(parameters, names.cursor)];
+
+        if (parameter !== undefined) {
+            parameter.cursor = {
+                baseIndex: parameterIndexFor(parameters, names.base),
+                lengthIndex: parameterIndexFor(parameters, names.length),
+            };
+        }
+    }
+};
+
+const bindMissingArrayExtent = (fn: GirFunction): GirFunction => {
+    const corrections = fn.cIdentifier === undefined ? undefined : PARAMETERS_MISSING_ARRAY_EXTENT.get(fn.cIdentifier);
+
+    if (corrections !== undefined) {
+        bindCursorParameters(fn.parameters, corrections);
+    }
+
+    return fn;
+};
+
 const functionFromNode = (node: RawNode, context: ParseContext): GirFunction => {
     const instanceNode = getChild(getChild(node, "parameters"), "instance-parameter");
 
-    return relaxMissingNullable({
-        ...parseCallable(node, context),
-        name: attr(node, "shadows") ?? attr(node, "name") ?? "",
-        cIdentifier: attr(node, "c:identifier"),
-        movedTo: attr(node, "moved-to"),
-        shadowedBy: attr(node, "shadowed-by"),
-        finishFunc: attr(node, "glib:finish-func"),
-        instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, context),
-    });
+    return bindMissingArrayExtent(
+        relaxMissingNullable({
+            ...parseCallable(node, context),
+            name: attr(node, "shadows") ?? attr(node, "name") ?? "",
+            cIdentifier: attr(node, "c:identifier"),
+            movedTo: attr(node, "moved-to"),
+            shadowedBy: attr(node, "shadowed-by"),
+            finishFunc: attr(node, "glib:finish-func"),
+            instance: instanceNode === undefined ? undefined : parameterFromNode(instanceNode, context),
+        }),
+    );
 };
 
 export { functionFromNode, type GirFunction };

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() {
@@ -294,7 +297,7 @@ class Library {
         seen.add(namespaceName);
         const path = locateGirFile(identifier, girPath);
         girFiles.push(path);
-        const header = parseNamespaceHeader(readRepositoryNode(path));
+        const header = parseNamespaceHeader(readRepositoryNode(path), path);
         const shell = this.registerNamespace(header);
         discovered.push({ header, shell });
 
@@ -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/namespace.ts

@@ -44,6 +44,8 @@ type GirNamespace = {
     id: number;
     /** Namespace name as it appears in the GIR, such as `Gtk`. */
     name: string;
+    /** Path of the `.gir` file the namespace was parsed from, named by every diagnostic the namespace causes. */
+    girFile: string;
     /** The `shared-library` attribute verbatim: the objects to load symbols from, separated by commas. */
     sharedLibrary: string | undefined;
     /** Prefixes stripped off C identifiers to derive export names, such as `gtk`. */
@@ -78,6 +80,8 @@ type NamespaceInclude = {
 type NamespaceHeader = {
     /** Namespace name as it appears in the GIR, such as `Gtk`. */
     name: string;
+    /** Path of the `.gir` file the header was read from. */
+    girFile: string;
     /** The `shared-library` attribute verbatim: the objects to load symbols from, separated by commas. */
     sharedLibrary: string | undefined;
     /** Prefixes stripped off C identifiers to derive export names, such as `gtk`. */
@@ -90,7 +94,7 @@ type NamespaceHeader = {
 
 const namespaceDirectory = (namespace: Pick<GirNamespace, "name">): string => namespace.name.toLowerCase();
 
-const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
+const parseNamespaceHeader = (repositoryNode: RawNode, path: string): NamespaceHeader => {
     const includes = getChildren(repositoryNode, "include").map<NamespaceInclude>((include) => ({
         name: nameAttr(include),
         version: attr(include, "version") ?? "",
@@ -99,11 +103,12 @@ const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
     const namespaceNode = getChildren(repositoryNode, "namespace")[0];
 
     if (namespaceNode === undefined) {
-        throw new Error("GIR repository has no <namespace> child");
+        throw new Error(`GIR file at ${path} has no <namespace> child in its <repository>`);
     }
 
     return {
         name: nameAttr(namespaceNode),
+        girFile: path,
         sharedLibrary: attr(namespaceNode, "shared-library"),
         cSymbolPrefixes: splitPrefixes(attr(namespaceNode, "c:symbol-prefixes")),
         includes,
@@ -114,6 +119,7 @@ const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
 const createNamespaceShell = (header: NamespaceHeader, id: number): GirNamespace => ({
     id,
     name: header.name,
+    girFile: header.girFile,
     sharedLibrary: header.sharedLibrary,
     cSymbolPrefixes: header.cSymbolPrefixes,
     classes: [],

package/src/gir/parameter.ts

@@ -23,6 +23,17 @@ type ParameterTransfer = "none" | "full" | "container";
  */
 type CallbackScope = "call" | "notified" | "async" | "forever";
 
+/**
+ * Bounds of an out parameter that points into the buffer of a sibling parameter instead of to an
+ * array of its own, which GIR describes as an array with no extent of any kind.
+ */
+type GirCursorBounds = {
+    /** Position of the parameter holding the buffer the pointer points into. */
+    baseIndex: number;
+    /** Position of the parameter carrying that buffer's element count. */
+    lengthIndex: number;
+};
+
 /** A parameter of a {@link GirCallable}, with the annotations that decide how it is marshalled. */
 type GirParameter = {
     /** The name GIR gives the parameter. */
@@ -51,6 +62,8 @@ type GirParameter = {
     destroyIndex: number | undefined;
     /** Whether the parameter is the `...` varargs marker. */
     isVarargs: boolean;
+    /** Where the buffer is that the parameter points into, when it carries a cursor rather than an array. */
+    cursor: GirCursorBounds | undefined;
 };
 
 /** What a {@link GirCallable} hands back, with the annotations that decide how it is marshalled. */
@@ -118,6 +131,7 @@ const parameterFromNode = (node: RawNode, context: ParseContext): GirParameter =
     closureIndex: intAttr(node, "closure"),
     destroyIndex: intAttr(node, "destroy"),
     isVarargs: getChild(node, "varargs") !== undefined,
+    cursor: undefined,
 });
 
 const isOutParameter = (parameter: GirParameter): boolean =>
@@ -163,6 +177,7 @@ export {
     isInoutParameter,
     parseCallable,
     type ParameterTransfer,
+    type GirCursorBounds,
     type GirParameter,
     type GirReturnValue,
     type GirCallable,

package/src/gir/parse.ts

@@ -1,9 +1,15 @@
-import { readFileSync } from "node:fs";
-import { createXmlParser } from "../xml.js";
+import { createXmlParser, parseXmlFile } from "../xml.js";
 
 /** An element of the parsed GIR XML: attributes under `@_`-prefixed keys, children under their tag names. */
 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",
@@ -42,11 +48,8 @@ function renameReservedTag(tag: string): string {
     return RESERVED_TAG_RENAMES.get(tag) ?? tag;
 }
 
-const parseGirFile = (path: string): RawNode => {
-    const xml = readFileSync(path, "utf8");
-
-    return PARSER.parse(xml) as RawNode;
-};
+const parseGirFile = (path: string): 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/guards.ts

@@ -0,0 +1,23 @@
+import { isRecord } from "@gtkx/utils";
+
+type Guard<T> = (value: unknown) => value is T;
+type OptionalGuard<T> = Guard<T | undefined> & { __optional__: true };
+type FieldGuard<T> = [undefined] extends [T] ? OptionalGuard<NonNullable<T>> : Guard<T>;
+type FieldGuards<T> = { [K in keyof Required<T>]: FieldGuard<T[K]> };
+
+const isBoolean = (value: unknown): value is boolean => typeof value === "boolean";
+const isNumber = (value: unknown): value is number => typeof value === "number";
+const isString = (value: unknown): value is string => typeof value === "string";
+
+const arrayGuard = <T>(isEntry: Guard<T>): Guard<T[]> =>
+    (value: unknown): value is T[] => Array.isArray(value) && value.every((entry: unknown) => isEntry(entry));
+
+const optionalGuard = <T>(isPresent: Guard<T>): OptionalGuard<T> =>
+    Object.assign((value: unknown): value is T | undefined => value === undefined || isPresent(value), {
+        __optional__: true as const,
+    });
+
+const hasFields = <T extends object>(value: unknown, guards: FieldGuards<T>): value is T =>
+    isRecord(value) && Object.entries(guards).every(([name, guard]) => (guard as Guard<unknown>)(value[name]));
+
+export { arrayGuard, hasFields, isBoolean, isNumber, isString, optionalGuard };

package/src/internal.ts

@@ -1,2 +1,4 @@
 export { writeDocs } from "./docs/pipeline.js";
 export { runGlCodegen } from "./runner.js";
+export { getShadowingStorePaths, sweepProjectStaging } from "./store/resolve-store.js";
+export { ensureStoreLinks } from "./store/store-links.js";

package/src/json.ts

@@ -0,0 +1,11 @@
+import { readFileSync } from "node:fs";
+
+const readJsonFile = (path: string): unknown => {
+    try {
+        return JSON.parse(readFileSync(path, "utf8")) as unknown;
+    } catch {
+        return undefined;
+    }
+};
+
+export { readJsonFile };

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/modules.ts

@@ -76,7 +76,10 @@ const renderEnumsModule = (tokens: EnumRow[], docs: GlDocContext): string => {
     const builder = new ModuleBuilder();
 
     for (const row of tokens) {
-        builder.appendDeclaration(`${enumJsDoc(row, docs)}\nexport const ${row.exportName} = ${row.literal};`);
+        builder.appendDeclaration({
+            name: row.exportName,
+            code: `${enumJsDoc(row, docs)}\nexport const ${row.exportName} = ${row.literal};`,
+        });
     }
 
     return `${generatedHeader(docs)}\n\n${builder.toSource()}`;
@@ -135,7 +138,11 @@ const appendScalarAliases = (builder: ModuleBuilder, docs: GlDocContext): void =
         }
 
         seen.add(scalar.tsAlias);
-        builder.appendDeclaration(`${scalarJsDoc(scalar.tsAlias, docs)}\nexport type ${scalar.tsAlias} = number;`);
+
+        builder.appendDeclaration({
+            name: scalar.tsAlias,
+            code: `${scalarJsDoc(scalar.tsAlias, docs)}\nexport type ${scalar.tsAlias} = number;`,
+        });
     }
 };
 
@@ -143,7 +150,10 @@ const appendGroupAliases = (builder: ModuleBuilder, groupAliases: Map<string, st
     const sorted = sortStringsBy(groupAliases.entries(), ([key]) => key);
 
     for (const [group, base] of sorted) {
-        builder.appendDeclaration(`${groupAliasJsDoc(group, base, docs)}\nexport type ${group} = ${base};`);
+        builder.appendDeclaration({
+            name: group,
+            code: `${groupAliasJsDoc(group, base, docs)}\nexport type ${group} = ${base};`,
+        });
     }
 };
 
@@ -151,12 +161,18 @@ const renderTypesModule = (groupAliases: Map<string, string>, docs: GlDocContext
     const builder = new ModuleBuilder();
     builder.imports.addNamed("@gtkx/native", "ExternalObject", true);
     builder.imports.addNamed("@gtkx/native", "Handle", true);
-    builder.appendDeclaration(`${syncJsDoc(docs)}\nexport type GLsync = ExternalObject<Handle>;`);
 
-    builder.appendDeclaration(
-        "/** An opaque native pointer handle (e.g. a `glMapBufferRange` mapping). */\n" +
-        "export type GLpointer = ExternalObject<Handle>;",
-    );
+    builder.appendDeclaration({
+        name: "GLsync",
+        code: `${syncJsDoc(docs)}\nexport type GLsync = ExternalObject<Handle>;`,
+    });
+
+    builder.appendDeclaration({
+        name: "GLpointer",
+        code:
+            "/** An opaque native pointer handle (e.g. a `glMapBufferRange` mapping). */\n" +
+            "export type GLpointer = ExternalObject<Handle>;",
+    });
 
     appendScalarAliases(builder, docs);
     appendGroupAliases(builder, groupAliases, docs);
@@ -184,7 +200,7 @@ const appendCommandBindings = (builder: ModuleBuilder, commands: RenderedCommand
 
 const appendCommandDeclarations = (builder: ModuleBuilder, commands: RenderedCommand[]): void => {
     for (const command of commands) {
-        builder.appendDeclaration(command.declaration);
+        builder.appendDeclaration({ name: command.exportName, code: command.declaration });
     }
 };
 

package/src/khronos/parse.ts

@@ -1,10 +1,10 @@
-import { readFileSync } from "node:fs";
-import { createXmlParser } from "../xml.js";
+import { createXmlParser, parseXmlFile } from "../xml.js";
 
 type OrderedNode = Record<string, unknown>;
 
 const ATTRIBUTES_KEY = ":@";
 const TEXT_KEY = "#text";
+const REGISTRY_LABEL = "OpenGL registry";
 
 const PARSER = createXmlParser({
     trimValues: false,
@@ -12,8 +12,7 @@ const PARSER = createXmlParser({
 });
 
 const parseRegistryFile = (path: string): OrderedNode[] => {
-    const xml = readFileSync(path, "utf8");
-    const documentNodes = PARSER.parse(xml) as OrderedNode[];
+    const documentNodes = parseXmlFile({ parser: PARSER, label: REGISTRY_LABEL, path }) as OrderedNode[];
 
     for (const node of documentNodes) {
         if (nodeTag(node) === "registry") {

package/src/khronos/pipeline.ts

@@ -387,4 +387,4 @@ const generateGlModules = (options: GlGenerationOptions): GlGenerationResult =>
     };
 };
 
-export { generateGlModules, type GlGenerationReport, type GlGenerationResult };
+export { generateGlModules, type GlGenerationReport };

package/src/khronos/plan.ts

@@ -328,7 +328,6 @@ const planCommand = (command: GlCommand, policy: GlPlanPolicy): CommandPlan => {
 
 export {
     GL_SCALARS,
-    parseCType,
     planCommand,
     type GlScalar,
     type ParamPlan,

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

@@ -2,12 +2,13 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { ModuleExport } from "./react/element-config.js";
 import type { OmittedProps } from "./store/jsx/omitted-props.js";
-import type { StoreOptions } from "./store/store-fs.js";
 import { checkModules } from "./compile.js";
 import { isGiStoreFresh } from "./fingerprint.js";
 import { runGiCodegen } from "./gi.js";
 import { Library } from "./gir/library.js";
 import { generateGlModules, type GlGenerationReport } from "./khronos/pipeline.js";
+import { sweepStagingDirs } from "./staging.js";
+import { ensureStoreLink, type StoreOptions } from "./store/store-fs.js";
 
 type GlCodegenOptions = {
     registryPath: string;
@@ -38,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. */
@@ -64,6 +67,10 @@ type StoreResult = {
  * store or the React element config changed, unless `options.isForced` is set. Pass the spread of
  * `resolveStore(projectRoot)` for everything but `libraries` and `girPath`.
  *
+ * Every store already on disk is linked at its `linkDir` before anything is generated, so a link an install
+ * pruned out of `node_modules` is restored without regenerating the store, and the gi store is reachable
+ * under its own specifier while the jsx store is type checked.
+ *
  * @param options What to generate and where to write it.
  * @returns A summary of what was regenerated and how long the run took.
  * @throws If `girPath` is empty, which would otherwise generate nothing and report success.
@@ -152,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) {
@@ -167,6 +176,17 @@ const emitStoresWithConfig = async (config: {
     return emitJsxStore({ options, jsx, gi, loadLibrary, isGiRegenerated, namespaces });
 };
 
+const prepareStores = (stores: (StoreOptions | undefined)[]): void => {
+    for (const store of stores) {
+        if (store === undefined) {
+            continue;
+        }
+
+        sweepStagingDirs(store.storeDir);
+        ensureStoreLink(store);
+    }
+};
+
 const emitStores = async (options: CodegenRunnerOptions): Promise<StoreResult> => {
     const { gi, jsx, libraries, girPath } = options;
 
@@ -174,6 +194,8 @@ const emitStores = async (options: CodegenRunnerOptions): Promise<StoreResult> =
         throw new Error("codegen needs at least one GIR search path; pass the result of resolveGirPath");
     }
 
+    prepareStores([gi, jsx]);
+
     return emitStoresWithConfig({ options, gi, jsx, libraries, girPath });
 };
 

package/src/staging.ts

@@ -0,0 +1,67 @@
+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 isOwnerRunning = (pid: number): boolean => {
+    if (!Number.isSafeInteger(pid) || pid <= 0) {
+        return false;
+    }
+
+    try {
+        process.kill(pid, 0);
+
+        return true;
+    } catch (error) {
+        return errorCode(error) === "EPERM";
+    }
+};
+
+const isStranded = (entry: string, prefix: string): boolean => {
+    if (!entry.startsWith(prefix)) {
+        return false;
+    }
+
+    const owner = OWNER_PATTERN.exec(entry.slice(prefix.length))?.groups?.pid;
+
+    return owner === undefined || !isOwnerRunning(Number(owner));
+};
+
+const readEntries = (parentDir: string): string[] => {
+    try {
+        return readdirSync(parentDir);
+    } catch {
+        return [];
+    }
+};
+
+const removeStrandedDir = (path: string): void => {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    } catch {
+        return;
+    }
+};
+
+const sweepStrandedDirs = (parentDir: string, prefix: string): void => {
+    for (const entry of readEntries(parentDir)) {
+        if (isStranded(entry, prefix)) {
+            removeStrandedDir(join(parentDir, entry));
+        }
+    }
+};
+
+const sweepStagingDirs = (target: string): void => {
+    sweepStrandedDirs(dirname(target), `${basename(target)}${STAGING_SUFFIX}`);
+};
+
+const createStagingDir = (target: string): string => {
+    mkdirSync(dirname(target), { recursive: true });
+    sweepStagingDirs(target);
+
+    return mkdtempSync(`${target}${STAGING_SUFFIX}${String(process.pid)}-`);
+};
+
+export { createStagingDir, sweepStagingDirs, sweepStrandedDirs };