@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/store/jsx/generated-elements.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { GlibNamedClass } from "./intrinsic-elements.js";
+import { namespaceDirectory } from "../../gir/namespace.js";
+
+/** One element the `@gtkx/jsx` store binds. */
+type GeneratedElement = {
+    /** GIR namespace name, such as `"Gtk"`. */
+    namespace: string;
+    /** Subexport the element is reachable through, such as `"gtk"` in `@gtkx/jsx/gtk`. */
+    directory: string;
+    /** GLib type name, which is also the JSX tag name, such as `"GtkButton"`. */
+    glibName: string;
+    /**
+     * Whether the element can be rendered. An abstract GType is bound for its props and metadata but
+     * exports no component, because `g_object_new` on one is a fatal GObject error.
+     */
+    isMountable: boolean;
+};
+
+const ELEMENTS_FILENAME = "elements.json";
+
+const collectGeneratedElements = (intrinsicElements: GlibNamedClass[]): GeneratedElement[] =>
+    intrinsicElements
+        .map((entry) => ({
+            namespace: entry.namespace.name,
+            directory: namespaceDirectory(entry.namespace),
+            glibName: entry.glibName,
+            isMountable: !entry.klass.isAbstract,
+        }))
+        .toSorted((a, b) => a.glibName.localeCompare(b.glibName));
+
+const renderGeneratedElements = (elements: GeneratedElement[]): string =>
+    `${JSON.stringify(elements, null, 2)}\n`;
+
+/**
+ * Reads the inventory of elements the `@gtkx/jsx` store binds, written into the store by codegen. Answers
+ * "what does this project's JSX layer cover" without loading the store, which resolves `virtual:` specifiers
+ * that only exist inside a Vite or Vitest build.
+ *
+ * @param jsxStoreDir The jsx store directory, as given by `resolveStore(projectRoot).jsx.storeDir`.
+ * @returns Every bound element, sorted by GLib type name, or an empty array when the store has no inventory.
+ */
+const readGeneratedElements = (jsxStoreDir: string): GeneratedElement[] => {
+    const path = join(jsxStoreDir, ELEMENTS_FILENAME);
+
+    if (!existsSync(path)) {
+        return [];
+    }
+
+    return JSON.parse(readFileSync(path, "utf8")) as GeneratedElement[];
+};
+
+export {
+    ELEMENTS_FILENAME,
+    collectGeneratedElements,
+    readGeneratedElements,
+    renderGeneratedElements,
+    type GeneratedElement,
+};

package/src/store/jsx/intrinsic-elements.ts

@@ -4,9 +4,13 @@ import type { Library } from "../../gir/library.js";
 import type { GirNamespace } from "../../gir/namespace.js";
 import { ancestorChain } from "../../gir/ancestry.js";
 
+/** A GIR class paired with the GLib type name it is bound under. */
 type GlibNamedClass = {
+    /** GLib type name, such as `"GtkButton"`, falling back to the C type when the GIR declares none. */
     glibName: string;
+    /** Parsed class the name belongs to. */
     klass: GirClass;
+    /** Namespace declaring the class. */
     namespace: GirNamespace;
 };
 

package/src/store/jsx/jsx.ts

@@ -3,8 +3,8 @@ import type { GirClass } from "../../gir/class.js";
 import type { Library } from "../../gir/library.js";
 import type { GirNamespace } from "../../gir/namespace.js";
 import type { ImportsBuilder } from "../../writer/imports.js";
-import { renderJsDoc } from "../../writer/doc.js";
 import { renderBlock } from "../../writer/emit.js";
+import { getDoc } from "../gi/doc-spec.js";
 import { elementPropTypeFor } from "./element-prop-imports.js";
 import {
     collectInterfacePropsClasses,
@@ -97,7 +97,9 @@ const generateJsxSection = (
     const intrinsicElementConsts = namespaceElements.filter((entry) => !excludeNames.has(entry.glibName));
 
     const constLines = intrinsicElementConsts.map(
-        (entry) => `export const ${entry.glibName} = ${sourceStringLiteral(entry.glibName)} as const;`,
+        (entry) =>
+            `${getDoc(entry.klass)}export const ${entry.glibName} = ` +
+            `${sourceStringLiteral(entry.glibName)} as const;`,
     );
 
     const isIntrinsicElementAncestor = (candidate: GirClass): boolean => {
@@ -109,7 +111,7 @@ const generateJsxSection = (
     addReactBuiltin(imports, "ReactNode");
     addReactBuiltin(imports, "Ref");
     const interfaceResult = renderInterfacePropBlocks(library, targetNamespace.name, options);
-    let isNeedsReactElement = interfaceResult.needsReactElement;
+    let requiresReactElement = interfaceResult.requiresReactElement;
     const propBlocks: string[] = [...interfaceResult.blocks];
 
     const blockContext: RenderPropBlockContext = {
@@ -124,18 +126,18 @@ const generateJsxSection = (
         const { block, objectPropNames } = renderPropBlock(library, entry, blockContext);
 
         if (objectPropNames.length > 0) {
-            isNeedsReactElement = true;
+            requiresReactElement = true;
         }
 
         propBlocks.push(block);
     }
 
-    if (isNeedsReactElement) {
+    if (requiresReactElement) {
         addReactBuiltin(imports, "ReactElement");
     }
 
     const source = [
-        constLines.join("\n"),
+        constLines.join("\n\n"),
         "",
         propBlocks.join("\n\n"),
         "",
@@ -152,11 +154,11 @@ const renderInterfacePropBlocks = (
     library: Library,
     targetNamespaceName: string,
     options: GenerateJsxOptions,
-): { blocks: string[]; needsReactElement: boolean; hasContainerProps: HasContainerProps } => {
+): { blocks: string[]; requiresReactElement: boolean; hasContainerProps: HasContainerProps } => {
     const { imports, intrinsicElements } = options;
     const context: InterfaceBlockContext = { library, targetNamespaceName, imports, hasContainerProps };
     const blocks: string[] = [];
-    let isNeedsReactElement = false;
+    let requiresReactElement = false;
 
     for (const iface of collectInterfacePropsClasses(
         library,
@@ -173,13 +175,13 @@ const renderInterfacePropBlocks = (
         const { block, objectPropNames } = renderInterfacePropsBlock(iface, glibName, context);
 
         if (objectPropNames.length > 0) {
-            isNeedsReactElement = true;
+            requiresReactElement = true;
         }
 
         blocks.push(block);
     }
 
-    return { blocks, needsReactElement: isNeedsReactElement, hasContainerProps };
+    return { blocks, requiresReactElement, hasContainerProps };
 };
 
 const registerCrossNsProps = (
@@ -285,7 +287,7 @@ const renderInterfacePropsBlock = (
     addGiNamespace(imports, iface.namespace.name, giNamespaceAlias(iface.namespace.name));
     const selfDefault = `${giNamespaceAlias(iface.namespace.name)}.${iface.klass.name}`;
     const signature = `export interface ${glib}Props<Self = ${selfDefault}>${extendsClause}`;
-    const block = `${renderJsDoc(iface.klass.doc)}${renderBlock(signature, ownerLines.join("\n"))}`;
+    const block = `${getDoc(iface.klass)}${renderBlock(signature, ownerLines.join("\n"))}`;
 
     return { block, objectPropNames };
 };
@@ -293,7 +295,7 @@ const renderInterfacePropsBlock = (
 const renderJsxAugmentation = (namespaceElements: GlibNamedClass[]): string => {
     const elementLines = namespaceElements
         .filter((entry) => !entry.klass.isAbstract)
-        .map((entry) => `${entry.glibName}: ${entry.glibName}Props;`)
+        .map((entry) => `${getDoc(entry.klass)}${entry.glibName}: ${entry.glibName}Props;`)
         .join("\n");
 
     const intrinsicInterface = renderBlock("interface IntrinsicElements", elementLines);
@@ -324,7 +326,7 @@ const renderPropBlock = (
     const extendsClause = extendsList.length === 0 ? "" : ` extends ${extendsList.join(", ")}`;
     const selfDefault = `${giNamespaceAlias(entry.namespace.name)}.${entry.klass.name}`;
 
-    const block = `${renderJsDoc(entry.klass.doc)}${renderBlock(
+    const block = `${getDoc(entry.klass)}${renderBlock(
         `export interface ${entry.glibName}Props<Self = ${selfDefault}>${extendsClause}`,
         ownerLines.join("\n"),
     )}`;

package/src/store/jsx/metadata.ts

@@ -23,7 +23,7 @@ type IntrinsicElementEntry = {
 };
 
 type PropNameCollector = {
-    keep: (property: GirProperty) => boolean;
+    shouldKeep: (property: GirProperty) => boolean;
     seen: Set<string>;
     names: string[];
 };
@@ -57,10 +57,10 @@ const generateMetadata = (library: Library): string => {
         .map(({ glibName, defaults }) => `    "${glibName}": ${renderDefaultsObject(defaults)},`);
 
     return `${[
-        `export const SIGNALS: Record<string, Record<string, string>> = {\n${signalsEntries.join("\n")}\n};`,
-        `export const CONSTRUCT_ONLY_PROPS: Record<string, Set<string>> = {\n${constructOnlyEntries.join("\n")}\n};`,
-        `export const CONSTRUCT_PROPS: Record<string, Set<string>> = {\n${constructableEntries.join("\n")}\n};`,
-        `export const DEFAULT_PROPS: Record<string, Record<string, unknown>> = {\n${defaultsEntries.join("\n")}\n};`,
+        `export const signals: Record<string, Record<string, string>> = {\n${signalsEntries.join("\n")}\n};`,
+        `export const constructOnlyProps: Record<string, Set<string>> = {\n${constructOnlyEntries.join("\n")}\n};`,
+        `export const constructProps: Record<string, Set<string>> = {\n${constructableEntries.join("\n")}\n};`,
+        `export const defaultProps: Record<string, Record<string, unknown>> = {\n${defaultsEntries.join("\n")}\n};`,
     ].join("\n\n")}\n`;
 };
 
@@ -114,10 +114,10 @@ const collectSignals = (sources: GirClass[]): [string, string][] => {
 };
 
 const collectPropNamesFromSource = (source: GirClass, collector: PropNameCollector): void => {
-    const { keep, seen, names } = collector;
+    const { shouldKeep, seen, names } = collector;
 
     for (const property of source.properties) {
-        if (!keep(property)) {
+        if (!shouldKeep(property)) {
             continue;
         }
 
@@ -133,7 +133,7 @@ const collectPropNamesFromSource = (source: GirClass, collector: PropNameCollect
 };
 
 const collectPropNames = (sources: GirClass[], shouldKeep: (property: GirProperty) => boolean): string[] => {
-    const collector: PropNameCollector = { keep: shouldKeep, seen: new Set<string>(), names: [] };
+    const collector: PropNameCollector = { shouldKeep, seen: new Set<string>(), names: [] };
 
     for (const source of sources) {
         collectPropNamesFromSource(source, collector);
@@ -362,9 +362,9 @@ const primitiveDefaultLiteral = (category: PrimitiveCategory, raw: string): stri
 };
 
 const bigintDefaultLiteral = (raw: string): string | undefined => {
-    const trimmed = raw.trim();
+    const integer = integerDefaultLiteral(raw);
 
-    return INTEGER_PATTERN.test(trimmed) ? `${trimmed}n` : undefined;
+    return integer === undefined ? undefined : `${integer}n`;
 };
 
 const enumDefaultLiteral = (enumType: GirEnum, raw: string): string | undefined => {

package/src/store/jsx/omitted-props.ts

@@ -3,7 +3,6 @@ type OmittedProps = Record<string, string[]>;
 
 const omittedProps: Map<string, Set<string>> = new Map();
 
-/** Installs the props each element omits (GLib type name → prop names); set once per run. */
 const setOmittedProps = (props: OmittedProps): void => {
     omittedProps.clear();
 
@@ -12,12 +11,11 @@ const setOmittedProps = (props: OmittedProps): void => {
     }
 };
 
-/** Whether the element config declares this prop omitted for the type that declares the property. */
 const isOmittedProp = (glibName: string | undefined, jsName: string): boolean =>
     glibName !== undefined && omittedProps.get(glibName)?.has(jsName) === true;
 
 /** Merges omitted-prop maps keyed by GLib type name, concatenating the names each map contributes. */
-const mergeOmitProps = (...maps: OmittedProps[]): OmittedProps => {
+const mergeOmittedProps = (...maps: OmittedProps[]): OmittedProps => {
     const merged: OmittedProps = {};
 
     for (const map of maps) {
@@ -29,4 +27,4 @@ const mergeOmitProps = (...maps: OmittedProps[]): OmittedProps => {
     return merged;
 };
 
-export { setOmittedProps, isOmittedProp, mergeOmitProps, type OmittedProps };
+export { setOmittedProps, isOmittedProp, mergeOmittedProps, type OmittedProps };

package/src/store/jsx/pipeline.ts

@@ -5,6 +5,7 @@ import { ImportsBuilder } from "../../writer/imports.js";
 import { type ElementComponentOverrides, generateElementComponentsSection } from "./element-components.js";
 import { type ElementProps, setElementProps } from "./element-prop-imports.js";
 import { type LazyElementSpec, lazyElementSpecs } from "./element-prop-types.js";
+import { collectGeneratedElements, type GeneratedElement } from "./generated-elements.js";
 import { buildGirIndex } from "./gir-index.js";
 import { collectIntrinsicElementClasses, type GlibNamedClass } from "./intrinsic-elements.js";
 import { generateJsxSection } from "./jsx.js";
@@ -20,13 +21,14 @@ type JsxFiles = {
     namespaces: JsxNamespaceFile[];
     metadata: string;
     intrinsicElementCount: number;
+    elements: GeneratedElement[];
 };
 
 type JsxGenerationOptions = {
     reactSubexports?: string[];
     components?: ElementComponentOverrides;
     props?: ElementProps;
-    omitProps?: OmittedProps;
+    omittedProps?: OmittedProps;
     lazyElements?: string[];
 };
 
@@ -49,7 +51,7 @@ type JsxNamespaceContext = {
 
 const generateJsxFiles = (library: Library, options: JsxGenerationOptions = {}): JsxFiles => {
     setElementProps(options.props ?? {});
-    setOmittedProps(options.omitProps ?? {});
+    setOmittedProps(options.omittedProps ?? {});
     const intrinsicElements = collectIntrinsicElementClasses(library);
     const intrinsicElementByGlibName = new Map(intrinsicElements.map((entry) => [entry.glibName, entry]));
     const girIndex = buildGirIndex(library);
@@ -66,7 +68,7 @@ const generateJsxFiles = (library: Library, options: JsxGenerationOptions = {}):
 
     const metadata = generateMetadata(library);
 
-    return { namespaces, metadata, intrinsicElementCount };
+    return { namespaces, metadata, intrinsicElementCount, elements: collectGeneratedElements(intrinsicElements) };
 };
 
 const orderedIntrinsicNamespaces = (intrinsicElements: GlibNamedClass[]): GirNamespace[] => {
@@ -145,4 +147,4 @@ const generateJsxNamespace = (
     return { source: `${body.join("\n")}\n`, count };
 };
 
-export { generateJsxFiles, type JsxNamespaceFile, type JsxGenerationOptions };
+export { generateJsxFiles, type JsxNamespaceFile };

package/src/store/jsx/props.ts

@@ -4,11 +4,13 @@ import type { Library } from "../../gir/library.js";
 import type { GirNamespace } from "../../gir/namespace.js";
 import type { GirCallable } from "../../gir/parameter.js";
 import type { TypeId } from "../../gir/type-id.js";
+import type { JsDocSpec } from "../../writer/doc.js";
 import { forEachAncestor } from "../../analysis/inheritance.js";
 import { renderHandlerParameters, renderHandlerResultType } from "../../analysis/param-structure.js";
 import { recordTypeTarget, renderBaseType, type TsTypeTarget } from "../../analysis/ts-type.js";
 import { type GirProperty, isConstructableProperty } from "../../gir/property.js";
 import { renderJsDoc } from "../../writer/doc.js";
+import { annotationSpec, selfHandlerSpec } from "../gi/doc-spec.js";
 import { getGlibName, giNamespaceAlias, isIntrinsicElementClass, signalHandlerName } from "./intrinsic-elements.js";
 import { isOmittedProp } from "./omitted-props.js";
 
@@ -67,9 +69,18 @@ type IntrinsicElementMemberWalk = IntrinsicElementScope & {
     acceptSignal: (signal: GirCallable) => void;
 };
 
+const notifyDoc = (property: GirProperty, jsName: string, spec: JsDocSpec): string => {
+    const note = `Called with the new value when \`${jsName}\` changes.`;
+    const doc = property.doc;
+    const text = doc === undefined || doc.length === 0 ? note : `${note}\n\n${doc}`;
+
+    return renderJsDoc(text, undefined, spec);
+};
+
 const appendPropertyLines = (state: PropCollectorState, property: GirProperty, jsName: string): void => {
     const tsType = renderReactPropType(state.types, property.type, false);
-    const doc = renderJsDoc(property.doc);
+    const spec = annotationSpec(property.annotations);
+    const doc = renderJsDoc(property.doc, undefined, spec);
 
     if (isObjectProp(state.owner.library, property)) {
         state.propLines.push(`${doc}${jsName}?: ${tsType} | ReactElement | null | undefined;`);
@@ -78,14 +89,15 @@ const appendPropertyLines = (state: PropCollectorState, property: GirProperty, j
         return;
     }
 
-    const isSettable = isConstructableProperty(property);
-
-    if (isSettable) {
+    if (isConstructableProperty(property)) {
         state.propLines.push(`${doc}${jsName}?: ${tsType} | null | undefined;`);
     }
 
     const handlerType = `((value: ${tsType} | null, self: Self) => void) | null | undefined`;
-    state.propLines.push(`${isSettable ? "" : doc}onNotify${upperFirst(jsName)}?: ${handlerType};`);
+
+    state.propLines.push(
+        `${notifyDoc(property, jsName, spec)}onNotify${upperFirst(jsName)}?: ${handlerType};`,
+    );
 };
 
 const acceptCollectorProperty = (state: PropCollectorState, property: GirProperty): void => {
@@ -112,7 +124,8 @@ const acceptCollectorSignal = (state: PropCollectorState, signal: GirCallable):
 
     state.seen.add(handlerName);
     const signature = renderSignalHandler({ types: state.types, signal, selfType: "Self" });
-    state.propLines.push(`${renderJsDoc(signal.doc)}${handlerName}?: (${signature}) | undefined;`);
+    const doc = renderJsDoc(signal.doc, undefined, selfHandlerSpec(signal));
+    state.propLines.push(`${doc}${handlerName}?: (${signature}) | undefined;`);
 };
 
 const createPropEntryCollector = (owner: IntrinsicElementScope): PropEntryCollector => {
@@ -231,8 +244,8 @@ const renderSignalHandler = (options: SignalRenderOptions): string => {
         library: types.library,
         signal,
         renderType: (ref, nullable) => renderReactPropType(types, ref, nullable),
-        includeCallerAllocated: false,
-        optOut: true,
+        shouldIncludeCallerAllocated: false,
+        isOptOut: true,
     });
 
     return `(${params.join(", ")}) => ${result}`;
@@ -259,4 +272,4 @@ const renderReactPropType = (context: PropTypeRenderContext, ref: TypeId | undef
     return isNullable ? `${base} | null` : base;
 };
 
-export { buildElementPropsEntries, buildInterfacePropsEntries, isObjectProp, reactTarget };
+export { buildElementPropsEntries, buildInterfacePropsEntries, isObjectProp };

package/src/store/jsx-store.ts

@@ -2,13 +2,11 @@ import type { JsxNamespaceFile } from "./jsx/pipeline.js";
 import type { RawFile } from "./store-fs.js";
 import { buildManifest, type StoreOptions, subpathExport, writeStore } from "./store-fs.js";
 
-type JsxStoreOptions = StoreOptions;
-
 const writeJsxStore = (
-    options: JsxStoreOptions,
+    options: StoreOptions,
     namespaces: JsxNamespaceFile[],
     metadata: string,
-    fingerprint: RawFile,
+    rawFiles: RawFile[],
 ): void => {
     const exportsMap: Record<string, unknown> = {
         "./metadata": subpathExport("metadata"),
@@ -31,9 +29,9 @@ const writeJsxStore = (
             exports: exportsMap,
             peerDependencies: { "@gtkx/gi": "*", "@gtkx/react": "*", react: "*" },
         }),
-        rawFiles: [fingerprint],
-        configEnv: true,
+        rawFiles,
+        requiresEnvReference: true,
     });
 };
 
-export { writeJsxStore, type JsxStoreOptions };
+export { writeJsxStore };

package/src/store/resolve-store.ts

@@ -0,0 +1,100 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, parse } from "node:path";
+import type { StoreOptions } from "./store-fs.js";
+
+/**
+ * Where a project's generated stores live, ready to spread into `runCodegen`. `jsx` is null when the
+ * project has no `@gtkx/react` installed, in which case only the `@gtkx/gi` store can be generated.
+ */
+type ResolvedStore = {
+    /** Where the `@gtkx/gi` store goes, versioned by the installed `@gtkx/runtime`. */
+    gi: StoreOptions;
+    /** Where the `@gtkx/jsx` store goes, versioned by the installed `@gtkx/react`; null when it is absent. */
+    jsx: StoreOptions | null;
+    /** Subexport names of the installed `@gtkx/react`, empty when it is absent. */
+    reactSubexports: string[];
+};
+
+type ResolvedPackage = { dir: string; version: string };
+
+const STORE_DIR = ".gtkx";
+const SCOPE = "@gtkx";
+
+const readManifest = (path: string): { version?: string; exports?: Record<string, unknown> } =>
+    JSON.parse(readFileSync(path, "utf8")) as { version?: string; exports?: Record<string, unknown> };
+
+const subexportNames = (packageDir: string): string[] =>
+    Object.keys(readManifest(join(packageDir, "package.json")).exports ?? {})
+        .filter((key) => key.startsWith("./") && key !== "./package.json")
+        .map((key) => key.slice(2));
+
+const loadPackage = (manifest: string): ResolvedPackage | null => {
+    if (!existsSync(manifest)) {
+        return null;
+    }
+
+    const real = realpathSync(manifest);
+
+    return { dir: dirname(real), version: readManifest(real).version ?? "0.0.0" };
+};
+
+const nodeModulesChain = function* (projectRoot: string): Generator<string> {
+    const { root } = parse(projectRoot);
+    let current = projectRoot;
+
+    while (current !== root) {
+        yield join(current, "node_modules");
+        current = dirname(current);
+    }
+
+    yield join(root, "node_modules");
+};
+
+const resolvePackage = (projectRoot: string, packageName: string): ResolvedPackage | null => {
+    for (const nodeModules of nodeModulesChain(projectRoot)) {
+        const found = loadPackage(join(nodeModules, packageName, "package.json"));
+
+        if (found !== null) {
+            return found;
+        }
+    }
+
+    return loadPackage(join(projectRoot, "packages", packageName.replace(/^@[^/]+\//, ""), "package.json"));
+};
+
+const storeOptions = (nodeModules: string, name: string, version: string): StoreOptions => ({
+    storeDir: join(nodeModules, STORE_DIR, name),
+    linkDir: join(nodeModules, SCOPE, name),
+    version,
+});
+
+/**
+ * Resolves where a project's `@gtkx/gi` and `@gtkx/jsx` stores belong, from the project root alone. The
+ * result supplies every `runCodegen` input except `libraries` and `girPath`, so a caller that has
+ * already resolved those can spread it straight into the call.
+ *
+ * Store versions come from the installed `@gtkx/runtime` and `@gtkx/react`, so a dependency upgrade
+ * invalidates the stores. Pass explicit `gi` or `jsx` options to `runCodegen` to override any of it.
+ *
+ * @param projectRoot Directory holding the project's `package.json` and `node_modules`.
+ * @returns The store locations and the React subexports that shape the jsx store.
+ * @throws If `@gtkx/runtime` cannot be resolved from the project.
+ */
+const resolveStore = (projectRoot: string): ResolvedStore => {
+    const runtime = resolvePackage(projectRoot, "@gtkx/runtime");
+
+    if (runtime === null) {
+        throw new Error(`Cannot resolve @gtkx/runtime from ${projectRoot}; is it installed?`);
+    }
+
+    const react = resolvePackage(projectRoot, "@gtkx/react");
+    const nodeModules = join(projectRoot, "node_modules");
+
+    return {
+        gi: storeOptions(nodeModules, "gi", runtime.version),
+        jsx: react === null ? null : storeOptions(nodeModules, "jsx", react.version),
+        reactSubexports: react === null ? [] : subexportNames(react.dir),
+    };
+};
+
+export { resolveStore, type ResolvedStore };

package/src/store/store-fs.ts

@@ -1,10 +1,14 @@
-import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { compileStore } from "./compile-store.js";
 
+/** Where one generated store is written and how it is reached. */
 type StoreOptions = {
+    /** Directory the generated package is written to, replaced atomically on each run. */
     storeDir: string;
+    /** Path the store is symlinked at, which is the specifier's resolution target under `node_modules`. */
     linkDir: string;
+    /** Version stamped on the store's `package.json`, taken from the dependency the store is generated for. */
     version: string;
 };
 
@@ -37,9 +41,11 @@ type WriteStoreParams = {
     files: StoreFile[];
     manifest: Manifest;
     rawFiles?: RawFile[];
-    configEnv?: boolean;
+    requiresEnvReference?: boolean;
 };
 
+const STORE_DIR_MODE = 0o755;
+
 const subpathExport = (stem: string): { types: string; default: string } => ({
     types: `./${stem}.d.ts`,
     default: `./${stem}.js`,
@@ -73,7 +79,7 @@ const writeStore = (params: WriteStoreParams): void => {
             storeDir: tmp,
             files: params.files,
             packageName: params.manifest.name,
-            ...(params.configEnv !== undefined && { configEnv: params.configEnv }),
+            ...(params.requiresEnvReference !== undefined && { requiresEnvReference: params.requiresEnvReference }),
         });
 
         writePackageJson(tmp, params.manifest);
@@ -83,7 +89,6 @@ const writeStore = (params: WriteStoreParams): void => {
             writeFileSync(join(tmp, raw.relativePath), raw.content);
         }
 
-        symlinkRelative(join(tmp, "node_modules", ...params.manifest.name.split("/")), tmp);
         swapStore(tmp, params.storeDir, params.linkDir);
     } finally {
         rmSync(tmp, { recursive: true, force: true });
@@ -121,8 +126,10 @@ const swapStore = (tmp: string, storeDir: string, visibleLink: string): void =>
 
 const createTempStore = (storeDir: string): string => {
     mkdirSync(dirname(storeDir), { recursive: true });
+    const tmp = mkdtempSync(`${storeDir}.tmp-`);
+    chmodSync(tmp, STORE_DIR_MODE);
 
-    return mkdtempSync(`${storeDir}.tmp-`);
+    return tmp;
 };
 
 export { subpathExport, buildManifest, writeStore, type StoreOptions, type RawFile };

package/src/writer/context.ts

@@ -1,6 +1,6 @@
 import type { Library } from "../gir/library.js";
 import type { GirNamespace } from "../gir/namespace.js";
-import { ModuleBuilder } from "./module.js";
+import { type DeclaredType, ModuleBuilder } from "./module.js";
 
 class ModuleContext {
     public module: ModuleBuilder = new ModuleBuilder();
@@ -55,6 +55,10 @@ class ModuleContext {
         return namespaceName;
     }
 
+    declaredType(owner: string, name: string = owner): DeclaredType {
+        return { name, owner: `${this.namespace.name}.${owner}` };
+    }
+
     qualify(namespaceName: string, typeName: string): string {
         if (namespaceName === this.namespace.name) {
             return typeName;