@gtkx/codegen 0.21.0

package/src/gir/qualify.ts

@@ -0,0 +1,64 @@
+import type { GirFunction } from "./function.js";
+import type { GirParameter } from "./parameter.js";
+import type { GirTypeRef } from "./type-ref.js";
+
+/**
+ * Stamps a default namespace onto an unqualified `named` reference and
+ * recurses into composite (`array`, `list`, `hashtable`) references.
+ *
+ * GIR omits the namespace when a reference points to a sibling in the same
+ * file. When writers walk a class hierarchy across namespaces, the parent's
+ * references must be qualified with the parent's namespace before they can be
+ * resolved against the repository.
+ *
+ * Returns `undefined` for an `undefined` input so callers can pass through
+ * void return types unchanged.
+ *
+ * @param ref - The reference to qualify, or `undefined`
+ * @param defaultNamespace - The namespace to stamp on unqualified refs
+ */
+export const qualifyTypeRef = (ref: GirTypeRef | undefined, defaultNamespace: string): GirTypeRef | undefined => {
+    if (ref === undefined) return undefined;
+    switch (ref.kind) {
+        case "named":
+            return { ...ref, namespaceName: ref.namespaceName ?? defaultNamespace };
+        case "array":
+            return { ...ref, element: qualifyTypeRef(ref.element, defaultNamespace) ?? ref.element };
+        case "list":
+            return { ...ref, element: qualifyTypeRef(ref.element, defaultNamespace) ?? ref.element };
+        case "hashtable":
+            return {
+                ...ref,
+                key: qualifyTypeRef(ref.key, defaultNamespace) ?? ref.key,
+                value: qualifyTypeRef(ref.value, defaultNamespace) ?? ref.value,
+            };
+        case "primitive":
+        case "callback":
+        case "varargs":
+            return ref;
+    }
+};
+
+const qualifyParameter = (parameter: GirParameter, defaultNamespace: string): GirParameter => ({
+    ...parameter,
+    type: qualifyTypeRef(parameter.type, defaultNamespace),
+});
+
+/**
+ * Re-roots every type reference of a callable to `defaultNamespace`.
+ *
+ * Interface methods are flattened onto each implementing class, but their
+ * GIR type references are unqualified relative to the interface's own
+ * namespace. Stamping the interface namespace onto the instance parameter,
+ * each regular parameter, and the return value lets the class writer resolve
+ * and import those references as if the method had been authored on the class.
+ *
+ * @param fn - The callable whose references to qualify
+ * @param defaultNamespace - The namespace the callable's references belong to
+ */
+export const qualifyFunction = (fn: GirFunction, defaultNamespace: string): GirFunction => ({
+    ...fn,
+    instance: fn.instance === undefined ? undefined : qualifyParameter(fn.instance, defaultNamespace),
+    parameters: fn.parameters.map((parameter) => qualifyParameter(parameter, defaultNamespace)),
+    returnValue: { ...fn.returnValue, type: qualifyTypeRef(fn.returnValue.type, defaultNamespace) },
+});

package/src/gir/repository.ts

@@ -0,0 +1,149 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type { GirBoxed } from "./boxed.js";
+import type { GirCallback } from "./callback.js";
+import type { GirClass } from "./class.js";
+import type { GirEnum } from "./enum.js";
+import { type GirNamespace, namespaceFromRepository } from "./namespace.js";
+import { parseGirFile } from "./parse.js";
+import type { GirTypeRef } from "./type-ref.js";
+
+/**
+ * Resolved entity that a {@link GirRepository.resolveNamed} call returns.
+ *
+ * Wraps the matching entity along with the namespace it lives in, so
+ * writers can pull the namespace identifier or shared library name without
+ * a second lookup.
+ */
+export type ResolvedNamed =
+    | { readonly kind: "class"; readonly namespace: GirNamespace; readonly value: GirClass }
+    | { readonly kind: "interface"; readonly namespace: GirNamespace; readonly value: GirClass }
+    | { readonly kind: "boxed"; readonly namespace: GirNamespace; readonly value: GirBoxed }
+    | { readonly kind: "enum"; readonly namespace: GirNamespace; readonly value: GirEnum }
+    | { readonly kind: "callback"; readonly namespace: GirNamespace; readonly value: GirCallback }
+    | {
+          readonly kind: "alias";
+          readonly namespace: GirNamespace;
+          readonly target: string | undefined;
+          readonly targetRef: GirTypeRef | undefined;
+      };
+
+/**
+ * In-memory database of every loaded GIR namespace, indexed by name.
+ *
+ * Construct via {@link loadGirRepository}; the public API after that is the
+ * `namespaces` map and {@link resolveNamed} for cross-namespace lookups.
+ */
+export class GirRepository {
+    /** Namespaces keyed by their unqualified name (e.g. `"Gtk"`, `"GLib"`). */
+    public readonly namespaces: ReadonlyMap<string, GirNamespace>;
+    /** Absolute paths of every `.gir` file loaded, for staleness fingerprinting. */
+    public readonly girFiles: readonly string[];
+    private readonly entityIndex: Map<string, ResolvedNamed>;
+
+    /**
+     * Constructs a repository from the supplied namespace map.
+     *
+     * Callers should prefer {@link loadGirRepository} which discovers and
+     * parses files for you.
+     *
+     * @param namespaces - Namespaces keyed by unqualified name
+     * @param girFiles - Absolute paths of the `.gir` files the namespaces came from
+     */
+    constructor(namespaces: ReadonlyMap<string, GirNamespace>, girFiles: readonly string[] = []) {
+        this.namespaces = namespaces;
+        this.girFiles = girFiles;
+        this.entityIndex = new Map();
+        for (const namespace of namespaces.values()) {
+            indexNamespace(this.entityIndex, namespace);
+        }
+    }
+
+    /**
+     * Looks up a type by `(namespace, name)`. Aliases are followed one step
+     * to their target. Returns `undefined` when neither the namespace nor a
+     * matching entity exists.
+     *
+     * @param namespaceName - Namespace to look in (e.g. `"GLib"`)
+     * @param typeName - Local type name within the namespace (e.g. `"Variant"`)
+     */
+    resolveNamed(namespaceName: string, typeName: string): ResolvedNamed | undefined {
+        const key = entityKey(namespaceName, typeName);
+        const direct = this.entityIndex.get(key);
+        if (direct !== undefined) return direct;
+        return undefined;
+    }
+}
+
+const entityKey = (namespaceName: string, typeName: string): string => `${namespaceName}.${typeName}`;
+
+const indexNamespace = (index: Map<string, ResolvedNamed>, namespace: GirNamespace): void => {
+    for (const value of namespace.classes) {
+        index.set(entityKey(namespace.name, value.name), { kind: "class", namespace, value });
+    }
+    for (const value of namespace.interfaces) {
+        index.set(entityKey(namespace.name, value.name), { kind: "interface", namespace, value });
+    }
+    for (const value of namespace.boxeds) {
+        index.set(entityKey(namespace.name, value.name), { kind: "boxed", namespace, value });
+    }
+    for (const value of namespace.enums) {
+        index.set(entityKey(namespace.name, value.name), { kind: "enum", namespace, value });
+    }
+    for (const value of namespace.callbacks) {
+        index.set(entityKey(namespace.name, value.name), { kind: "callback", namespace, value });
+    }
+    for (const alias of namespace.aliases) {
+        const target = alias.target?.kind === "named" ? alias.target.typeName : undefined;
+        index.set(entityKey(namespace.name, alias.name), {
+            kind: "alias",
+            namespace,
+            target,
+            targetRef: alias.target,
+        });
+    }
+};
+
+/**
+ * Discovers and parses every GIR file needed to satisfy `libraries` and
+ * their transitive `<include>` dependencies.
+ *
+ * @param libraries - Resolved `Name-Version` namespace identifiers
+ * @param girPath - Ordered list of directories to search for `.gir` files
+ * @returns A populated {@link GirRepository}
+ * @throws If any required GIR file cannot be located on `girPath`
+ */
+export const loadGirRepository = (libraries: readonly string[], girPath: readonly string[]): GirRepository => {
+    const namespaces = new Map<string, GirNamespace>();
+    const girFiles: string[] = [];
+    const queue: string[] = [...libraries];
+    while (queue.length > 0) {
+        const identifier = queue.shift();
+        if (identifier === undefined) continue;
+        const namespaceName = identifier.split("-")[0] ?? identifier;
+        if (namespaces.has(namespaceName)) continue;
+        const path = locateGirFile(identifier, girPath);
+        girFiles.push(path);
+        const root = parseGirFile(path);
+        const repository = root.repository;
+        if (typeof repository !== "object" || repository === null) {
+            throw new Error(`GIR file at ${path} has no <repository> root`);
+        }
+        const namespace = namespaceFromRepository(repository as Record<string, unknown>);
+        namespaces.set(namespace.name, namespace);
+        for (const include of namespace.includes) {
+            queue.push(`${include.name}-${include.version}`);
+        }
+    }
+    return new GirRepository(namespaces, girFiles);
+};
+
+const locateGirFile = (identifier: string, girPath: readonly string[]): string => {
+    const filename = `${identifier}.gir`;
+    for (const directory of girPath) {
+        const candidate = join(directory, filename);
+        if (existsSync(candidate)) return candidate;
+    }
+    const tried = girPath.map((directory) => join(directory, filename)).join(", ");
+    throw new Error(`GIR file ${filename} not found on girPath. Tried: ${tried}`);
+};

package/src/gir/signal.ts

@@ -0,0 +1,36 @@
+import { type GirParameter, type GirReturnValue, parameterFromNode, returnValueFromNode } from "./parameter.js";
+import { attr, attrBool, childOf, childrenOf, type RawNode } from "./parse.js";
+
+/** Emission stage (`<glib:signal when="…">`). */
+type SignalWhen = "first" | "last" | "cleanup";
+
+/** A GObject `<glib:signal>` declaration. */
+export type GirSignal = {
+    /** GIR signal name, kebab-case (e.g. `"activate-link"`). */
+    readonly name: string;
+    readonly parameters: readonly GirParameter[];
+    readonly returnValue: GirReturnValue;
+    readonly when: SignalWhen;
+    readonly detailed: boolean;
+    readonly action: boolean;
+    readonly noRecurse: boolean;
+    readonly noHooks: boolean;
+};
+
+/**
+ * Builds a {@link GirSignal} from a `<glib:signal>` element.
+ */
+export const signalFromNode = (node: RawNode): GirSignal => {
+    const parametersNode = childOf(node, "parameters");
+    const parameterNodes = childrenOf(parametersNode, "parameter");
+    return {
+        name: attr(node, "name") ?? "",
+        parameters: parameterNodes.map((parameter) => parameterFromNode(parameter, false)),
+        returnValue: returnValueFromNode(childOf(node, "return-value")),
+        when: (attr(node, "when") ?? "last") as SignalWhen,
+        detailed: attrBool(node, "detailed"),
+        action: attrBool(node, "action"),
+        noRecurse: attrBool(node, "no-recurse"),
+        noHooks: attrBool(node, "no-hooks"),
+    };
+};

package/src/gir/size.ts

@@ -0,0 +1,129 @@
+import { PRIMITIVE_SIZE, type PrimitiveCategory } from "./primitives.js";
+
+/**
+ * Size and alignment of a single field as it appears in a C struct laid out
+ * according to the x86-64 ABI.
+ */
+export type FieldLayout = {
+    /** Width of the field in bytes. */
+    readonly size: number;
+    /** Required alignment in bytes; storage offset rounds up to a multiple of this. */
+    readonly align: number;
+};
+
+/**
+ * Returns the `{ size, align }` pair for a primitive category.
+ *
+ * Pointers and pointer-sized integers (the `pointer` and 64-bit categories)
+ * report 8/8. Smaller integers and floats report their natural width.
+ *
+ * @param category - The primitive category
+ */
+export const layoutOfPrimitive = (category: PrimitiveCategory): FieldLayout => {
+    const size = PRIMITIVE_SIZE[category];
+    return { size, align: size === 0 ? 1 : size };
+};
+
+const roundUp = (value: number, multiple: number): number => {
+    if (multiple <= 1) return value;
+    const remainder = value % multiple;
+    return remainder === 0 ? value : value + (multiple - remainder);
+};
+
+/**
+ * Layout slot for a single field that may participate in bitfield packing.
+ *
+ * `byteOffset` is always the offset of the underlying storage word; for
+ * non-bitfield fields it is the field's offset directly, and for bitfield
+ * members it is the start of the shared storage unit. `bitOffset` and
+ * `bitWidth` are populated only for bitfield members.
+ */
+export type FieldSlot = {
+    /** Byte offset of the storage word the field occupies. */
+    readonly byteOffset: number;
+    /** Bit position within the storage word, for bitfield members. */
+    readonly bitOffset: number | undefined;
+    /** Width in bits, for bitfield members. */
+    readonly bitWidth: number | undefined;
+};
+
+/**
+ * Describes a field for the purposes of layout computation.
+ */
+export type FieldLayoutInput = {
+    /** Natural byte size and alignment of the field's value type. */
+    readonly layout: FieldLayout;
+    /** When set, the field is a bitfield member with this many bits. */
+    readonly bits: number | undefined;
+};
+
+/**
+ * Computes per-field byte offsets for a record, grouping consecutive
+ * bitfield members of compatible storage widths into a shared storage
+ * word.
+ *
+ * Mirrors the GCC/Itanium ABI rules for C bitfield packing in a
+ * single-storage-word model: a new storage word is opened when the
+ * underlying type's size changes, when the new field is not a bitfield,
+ * or when adding the bits would exceed the word's bit count.
+ *
+ * A union (`isUnion`) overlays every member at byte offset 0; its size is the
+ * largest member rounded up to the strongest member alignment.
+ *
+ * @param fields - Ordered field layouts and bit widths
+ * @param isUnion - Whether the fields are union members (overlaid at offset 0)
+ * @returns Parallel slot array and the total record size in bytes
+ */
+export const computeFieldSlots = (
+    fields: readonly FieldLayoutInput[],
+    isUnion = false,
+): { readonly slots: readonly FieldSlot[]; readonly size: number } => {
+    if (isUnion) {
+        let maxSize = 0;
+        let maxAlign = 1;
+        const unionSlots = fields.map((field) => {
+            maxSize = Math.max(maxSize, field.layout.size);
+            maxAlign = Math.max(maxAlign, field.layout.align);
+            return { byteOffset: 0, bitOffset: field.bits === undefined ? undefined : 0, bitWidth: field.bits };
+        });
+        return { slots: unionSlots, size: roundUp(maxSize, maxAlign) };
+    }
+    const slots: FieldSlot[] = [];
+    let cursor = 0;
+    let maxAlign = 1;
+    let bitfieldWordOffset: number | undefined;
+    let bitfieldWordSize = 0;
+    let bitfieldUsedBits = 0;
+    for (const field of fields) {
+        const align = Math.max(1, field.layout.align);
+        if (align > maxAlign) maxAlign = align;
+        if (field.bits === undefined) {
+            bitfieldWordOffset = undefined;
+            bitfieldWordSize = 0;
+            bitfieldUsedBits = 0;
+            cursor = roundUp(cursor, align);
+            slots.push({ byteOffset: cursor, bitOffset: undefined, bitWidth: undefined });
+            cursor += field.layout.size;
+            continue;
+        }
+        const wordSizeBits = field.layout.size * 8;
+        const fits =
+            bitfieldWordOffset !== undefined &&
+            bitfieldWordSize === field.layout.size &&
+            bitfieldUsedBits + field.bits <= wordSizeBits;
+        if (!fits) {
+            cursor = roundUp(cursor, align);
+            bitfieldWordOffset = cursor;
+            bitfieldWordSize = field.layout.size;
+            bitfieldUsedBits = 0;
+            cursor += field.layout.size;
+        }
+        slots.push({
+            byteOffset: bitfieldWordOffset ?? 0,
+            bitOffset: bitfieldUsedBits,
+            bitWidth: field.bits,
+        });
+        bitfieldUsedBits += field.bits;
+    }
+    return { slots, size: roundUp(cursor, maxAlign) };
+};

package/src/gir/type-ref.ts

@@ -0,0 +1,180 @@
+import { attr, attrBool, childOf, childrenOf, type RawNode } from "./parse.js";
+import { type PrimitiveCategory, primitiveCategory } from "./primitives.js";
+
+/**
+ * Lazily-resolved reference to a GIR type as it appears in a `<type>` or
+ * `<array>` slot.
+ *
+ * The reference captures everything the writers need at emission time
+ * without forcing entity resolution to happen at parse time (which would
+ * impose a topological-sort order on namespace loading). Resolution into a
+ * concrete `GirClass` / `GirBoxed` / `GirEnum` / … is performed on demand
+ * by the writers via `GirRepository.resolveNamed`.
+ */
+export type GirTypeRef =
+    | PrimitiveTypeRef
+    | NamedTypeRef
+    | ArrayTypeRef
+    | ListTypeRef
+    | HashTableTypeRef
+    | InlineCallbackTypeRef
+    | VarargsTypeRef;
+
+/** A GIR scalar primitive: `gint`, `gboolean`, `utf8`, `gpointer`, etc. */
+export type PrimitiveTypeRef = {
+    readonly kind: "primitive";
+    readonly category: PrimitiveCategory;
+    readonly cType: string | undefined;
+};
+
+/**
+ * A named type that resolves to a class, interface, boxed, enum, alias, or
+ * fundamental in some namespace.
+ *
+ * `namespaceName` is the namespace prefix from the GIR (`"GLib"`, `"Gtk"`,
+ * …) or `undefined` for an unqualified reference. The unqualified form
+ * implies "look in the namespace the reference appears in".
+ */
+export type NamedTypeRef = {
+    readonly kind: "named";
+    readonly namespaceName: string | undefined;
+    readonly typeName: string;
+    readonly cType: string | undefined;
+};
+
+/** A C array (`<array>`) with optional length, fixed-size, or zero-terminated metadata. */
+export type ArrayTypeRef = {
+    readonly kind: "array";
+    readonly element: GirTypeRef;
+    readonly cType: string | undefined;
+    readonly lengthParameterIndex: number | undefined;
+    readonly fixedSize: number | undefined;
+    readonly zeroTerminated: boolean;
+};
+
+/** A GLib `GList` / `GSList` / `GPtrArray` / `GArray` / `GByteArray`. */
+export type ListTypeRef = {
+    readonly kind: "list";
+    readonly flavor: "glist" | "gslist" | "gptrarray" | "garray" | "gbytearray";
+    readonly element: GirTypeRef;
+    readonly cType: string | undefined;
+};
+
+/** A GLib `GHashTable` with key and value element types. */
+export type HashTableTypeRef = {
+    readonly kind: "hashtable";
+    readonly key: GirTypeRef;
+    readonly value: GirTypeRef;
+    readonly cType: string | undefined;
+};
+
+/** An inline `<callback>` (used for vtable slots and callback parameters). */
+type InlineCallbackTypeRef = {
+    readonly kind: "callback";
+    readonly callback: RawNode;
+};
+
+/** A `<varargs/>` parameter placeholder; not marshalable. */
+type VarargsTypeRef = { readonly kind: "varargs" };
+
+const LIST_KIND_BY_NAME: ReadonlyMap<string, "glist" | "gslist" | "gptrarray" | "garray" | "gbytearray"> = new Map([
+    ["GLib.List", "glist"],
+    ["GLib.SList", "gslist"],
+    ["GLib.PtrArray", "gptrarray"],
+    ["GLib.Array", "garray"],
+    ["GLib.ByteArray", "gbytearray"],
+] as const);
+
+/**
+ * Builds a {@link GirTypeRef} from a parent XML node whose first `<type>`,
+ * `<array>`, or `<varargs>` child describes the slot.
+ *
+ * Pass the parent (`<parameter>`, `<return-value>`, `<field>`, `<property>`,
+ * `<constant>`, `<alias>`). The helper extracts the right child and routes
+ * to {@link typeRefFromTypeNode}.
+ *
+ * @param parent - The element whose typed slot we are inspecting
+ * @returns The reference, or `undefined` if no type slot exists
+ */
+export const typeRefFromSlot = (parent: RawNode | undefined): GirTypeRef | undefined => {
+    if (parent === undefined) return undefined;
+    if (childOf(parent, "varargs") !== undefined) return { kind: "varargs" };
+    const arrayNode = childOf(parent, "array");
+    if (arrayNode !== undefined) return arrayTypeRefFromNode(arrayNode);
+    const typeNode = childOf(parent, "type");
+    if (typeNode !== undefined) return typeRefFromTypeNode(typeNode);
+    const callback = childOf(parent, "callback");
+    if (callback !== undefined) return { kind: "callback", callback };
+    return undefined;
+};
+
+/**
+ * Builds a {@link GirTypeRef} from a `<type>` element.
+ *
+ * Splits a `Namespace.TypeName` form into namespace + type, recognises GLib
+ * container types (`GLib.List`, `GLib.HashTable`, …) by name and routes
+ * them to the dedicated branches, otherwise produces a primitive or named
+ * reference for later resolution.
+ *
+ * @param typeNode - A `<type>` element
+ */
+const typeRefFromTypeNode = (typeNode: RawNode): GirTypeRef => {
+    const name = attr(typeNode, "name") ?? "";
+    const cType = attr(typeNode, "c:type");
+
+    const listFlavor = LIST_KIND_BY_NAME.get(name);
+    if (listFlavor !== undefined) {
+        const elementNode = childOf(typeNode, "type");
+        const element = elementNode === undefined ? pointerFallback() : typeRefFromTypeNode(elementNode);
+        return { kind: "list", flavor: listFlavor, element, cType };
+    }
+
+    if (name === "GLib.HashTable") {
+        const elementTypes = childrenOf(typeNode, "type");
+        const keyNode = elementTypes[0];
+        const valueNode = elementTypes[1];
+        return {
+            kind: "hashtable",
+            key: keyNode === undefined ? pointerFallback() : typeRefFromTypeNode(keyNode),
+            value: valueNode === undefined ? pointerFallback() : typeRefFromTypeNode(valueNode),
+            cType,
+        };
+    }
+
+    const primitive = primitiveCategory(name);
+    if (primitive !== undefined) {
+        return { kind: "primitive", category: primitive, cType };
+    }
+
+    const [namespaceName, typeName] = splitOptionalNamespace(name);
+    return { kind: "named", namespaceName, typeName, cType };
+};
+
+const arrayTypeRefFromNode = (arrayNode: RawNode): ArrayTypeRef | ListTypeRef => {
+    const elementNode = childOf(arrayNode, "type");
+    const element: GirTypeRef = elementNode === undefined ? pointerFallback() : typeRefFromTypeNode(elementNode);
+    const cType = attr(arrayNode, "c:type");
+    const arrayName = attr(arrayNode, "name");
+    const listFlavor = arrayName === undefined ? undefined : LIST_KIND_BY_NAME.get(arrayName);
+    if (listFlavor !== undefined) {
+        return { kind: "list", flavor: listFlavor, element, cType };
+    }
+    const lengthAttr = attr(arrayNode, "length");
+    const fixedSizeAttr = attr(arrayNode, "fixed-size");
+    return {
+        kind: "array",
+        element,
+        cType,
+        lengthParameterIndex: lengthAttr === undefined ? undefined : Number.parseInt(lengthAttr, 10),
+        fixedSize: fixedSizeAttr === undefined ? undefined : Number.parseInt(fixedSizeAttr, 10),
+        zeroTerminated: attrBool(arrayNode, "zero-terminated", false),
+    };
+};
+
+const pointerFallback = (): PrimitiveTypeRef => ({ kind: "primitive", category: "pointer", cType: undefined });
+
+const splitOptionalNamespace = (name: string): [string | undefined, string] => {
+    const dot = name.indexOf(".");
+    if (dot === -1) return [undefined, name];
+    return [name.slice(0, dot), name.slice(dot + 1)];
+};

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Public API of `@gtkx/codegen`.
+ *
+ * The package exposes a single entry point — {@link CodegenRunner} — that
+ * orchestrates the GIR-driven code generation for the FFI and React
+ * surfaces. Internal modules (`gir/`, `dsl/`, `writers/`, `ffi/`,
+ * `react/`) are not part of the supported surface and may change in any
+ * release.
+ */
+export {
+    CODEGEN_VERSION,
+    type CodegenFingerprint,
+    computeFingerprint,
+    FINGERPRINT_FILENAME,
+} from "./fingerprint.js";
+export { CodegenRunner } from "./runner.js";

package/src/jsx-store.ts

@@ -0,0 +1,53 @@
+import { type StoreOptions, writeStore } from "./store-fs.js";
+
+/**
+ * Options for assembling the injected `@gtkx/react-jsx` unit.
+ */
+export type JsxStoreOptions = StoreOptions & {
+    /** Absolute path to the gi store, for the unit's own `node_modules/@gtkx/gi`. */
+    readonly giStoreDir: string;
+    /** Real (symlink-resolved) directory of the installed `react` runtime. */
+    readonly realReactRuntimeDir: string;
+    /** Real (symlink-resolved) directory of the installed `@gtkx/react`. */
+    readonly realReactPackageDir: string;
+};
+
+const stem = (relativePath: string): string => relativePath.replace(/\.(tsx|ts)$/, "");
+
+/**
+ * Assembles the self-contained injected `@gtkx/react-jsx` unit: the generated
+ * `jsx`/`internal`/`compounds` modules plus a `package.json` and the unit's own
+ * `node_modules` symlinks to `@gtkx/gi` and `react`.
+ *
+ * @param options - Resolved store/link/dependency paths
+ * @param files - React pipeline output keyed by source filename
+ */
+export const writeJsxStore = (options: JsxStoreOptions, files: ReadonlyMap<string, string>): void => {
+    writeStore({
+        storeDir: options.storeDir,
+        linkDir: options.linkDir,
+        files: [...files].map(([relativePath, source]) => ({
+            stem: stem(relativePath),
+            fileName: relativePath,
+            source,
+        })),
+        manifest: {
+            name: "@gtkx/react-jsx",
+            type: "module",
+            version: options.version,
+            sideEffects: ["./internal.js"],
+            exports: {
+                "./package.json": "./package.json",
+                ".": { types: "./jsx.d.ts", default: "./jsx.js" },
+                "./jsx": { types: "./jsx.d.ts", default: "./jsx.js" },
+                "./compounds": { types: "./compounds.d.ts", default: "./compounds.js" },
+                "./internal": { types: "./internal.d.ts", default: "./internal.js" },
+            },
+        },
+        symlinks: [
+            { segments: ["node_modules", "@gtkx", "gi"], target: options.giStoreDir },
+            { segments: ["node_modules", "@gtkx", "react"], target: options.realReactPackageDir },
+            { segments: ["node_modules", "react"], target: options.realReactRuntimeDir },
+        ],
+    });
+};