@gtkx/codegen 1.0.0-rc.4 → 1.1.0

package/src/store/jsx/element-components.ts

@@ -3,7 +3,7 @@ import type { Library } from "../../gir/library.js";
 import type { GirNamespace } from "../../gir/namespace.js";
 import type { ImportsBuilder } from "../../writer/imports.js";
 import type { LazyElementSpec } from "./element-prop-types.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import { getDoc } from "../gi/doc-spec.js";
 import { ancestorGlibNames, type GlibNamedClass } from "./intrinsic-elements.js";
 
 type ElementComponent = { module: string; export: string };
@@ -91,10 +91,11 @@ const collectLazyElementExports = (collector: ExportCollector, lazyElements: Laz
 };
 
 const renderLazyElementExport = (spec: LazyElementSpec): string => {
+    const doc = getDoc(spec);
     const factory = `createElementComponent(${sourceStringLiteral(spec.element)})`;
-    const component = `export const ${spec.element}: (props: ${spec.typeName}) => ReactNode = ${factory};`;
+    const component = `${doc}export const ${spec.element}: (props: ${spec.typeName}) => ReactNode = ${factory};`;
 
-    return `${spec.typeSource}\n\n${component}`;
+    return `${doc}${spec.typeSource}\n\n${component}`;
 };
 
 const renderCandidateExport = (
@@ -113,7 +114,9 @@ const renderCandidateExport = (
         imports.addNamed(component.module, component.export, false);
     }
 
-    return `${renderJsDoc(klass.doc)}${renderElementComponentExport(glibName, component)}`;
+    const doc = getDoc(klass);
+
+    return `${doc}${renderElementComponentExport(glibName, component)}`;
 };
 
 const resolveElementComponent = (
@@ -143,4 +146,4 @@ const renderElementComponentExport = (glibName: string, component: ElementCompon
     return `export const ${glibName}: ${annotation} = ${component.export}(${factoryCall});`;
 };
 
-export { generateElementComponentsSection, type ElementComponent, type ElementComponentOverrides };
+export { generateElementComponentsSection, type ElementComponentOverrides };

package/src/store/jsx/element-prop-imports.ts

@@ -2,9 +2,7 @@ type ElementPropTypeRef = { type: string; module: string; export: string };
 
 /** Base props interface each element extends, keyed by GLib type name (the module exports it). */
 type ElementProps = Record<string, {
-    /** Specifier the props interface is imported from. */
     module: string;
-    /** Identifier the module exports it under. */
     export: string;
 }>;
 
@@ -24,4 +22,4 @@ const elementPropTypeFor = (glibName: string): ElementPropTypeRef | undefined =>
     return ref === undefined ? undefined : { type: glibName, module: ref.module, export: ref.export };
 };
 
-export { setElementProps, elementPropTypeFor, type ElementPropTypeRef, type ElementProps };
+export { setElementProps, elementPropTypeFor, type ElementProps };

package/src/store/jsx/element-prop-types.ts

@@ -1,4 +1,5 @@
 import { toCamelIdentifier } from "@gtkx/utils";
+import type { GirAnnotations } from "../../gir/annotations.js";
 import type { GirClass } from "../../gir/class.js";
 import { getChain, type GirIndex, type GirTypeEntry } from "./gir-index.js";
 import { getGlibName } from "./intrinsic-elements.js";
@@ -7,6 +8,8 @@ type LazyElementSpec = {
     element: string;
     typeName: string;
     typeSource: string;
+    doc: string | undefined;
+    annotations: GirAnnotations;
 };
 
 const appendConstructOnlyNames = (klass: GirClass, names: string[]): void => {
@@ -34,7 +37,13 @@ const createLazyElementSpec = (context: GirIndex, element: string, entry: GirTyp
     const omitUnion = omitted.map((name) => JSON.stringify(name)).join(" | ");
     const base = omitted.length === 0 ? `${baseName}Props` : `Omit<${baseName}Props, ${omitUnion}>`;
 
-    return { element, typeName, typeSource: `export type ${typeName} = ${base} & { children?: ReactNode };` };
+    return {
+        element,
+        typeName,
+        typeSource: `export type ${typeName} = ${base} & { children?: ReactNode };`,
+        doc: entry.klass.doc,
+        annotations: entry.klass.annotations,
+    };
 };
 
 const lazyElementSpecs = (context: GirIndex, lazyElements: string[]): Map<string, LazyElementSpec[]> => {

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

@@ -1,7 +1,8 @@
-import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { GlibNamedClass } from "./intrinsic-elements.js";
 import { namespaceDirectory } from "../../gir/namespace.js";
+import { arrayGuard, hasFields, isBoolean, isString } from "../../guards.js";
+import { readJsonFile } from "../../json.js";
 
 /** One element the `@gtkx/jsx` store binds. */
 type GeneratedElement = {
@@ -33,22 +34,30 @@ const collectGeneratedElements = (intrinsicElements: GlibNamedClass[]): Generate
 const renderGeneratedElements = (elements: GeneratedElement[]): string =>
     `${JSON.stringify(elements, null, 2)}\n`;
 
+const isGeneratedElement = (value: unknown): value is GeneratedElement =>
+    hasFields<GeneratedElement>(value, {
+        namespace: isString,
+        directory: isString,
+        glibName: isString,
+        isMountable: isBoolean,
+    });
+
+const isGeneratedInventory = (value: unknown): value is GeneratedElement[] =>
+    arrayGuard(isGeneratedElement)(value);
+
 /**
  * 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.
+ * @returns Every bound element, sorted by GLib type name, or an empty array when the store holds no inventory
+ * codegen wrote, which covers an absent, unreadable, unparseable and structurally foreign store file alike.
  */
 const readGeneratedElements = (jsxStoreDir: string): GeneratedElement[] => {
-    const path = join(jsxStoreDir, ELEMENTS_FILENAME);
-
-    if (!existsSync(path)) {
-        return [];
-    }
+    const parsed = readJsonFile(join(jsxStoreDir, ELEMENTS_FILENAME));
 
-    return JSON.parse(readFileSync(path, "utf8")) as GeneratedElement[];
+    return isGeneratedInventory(parsed) ? parsed : [];
 };
 
 export {

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

@@ -1,10 +1,10 @@
-import { sourceStringLiteral } from "@gtkx/utils";
+import { sanitizeTypeIdentifier, sourceStringLiteral } from "@gtkx/utils";
 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 => {
@@ -135,7 +137,7 @@ const generateJsxSection = (
     }
 
     const source = [
-        constLines.join("\n"),
+        constLines.join("\n\n"),
         "",
         propBlocks.join("\n\n"),
         "",
@@ -283,9 +285,9 @@ const renderInterfacePropsBlock = (
 
     const extendsClause = prerequisiteExtends.length === 0 ? "" : ` extends ${prerequisiteExtends.join(", ")}`;
     addGiNamespace(imports, iface.namespace.name, giNamespaceAlias(iface.namespace.name));
-    const selfDefault = `${giNamespaceAlias(iface.namespace.name)}.${iface.klass.name}`;
+    const selfDefault = `${giNamespaceAlias(iface.namespace.name)}.${sanitizeTypeIdentifier(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);
@@ -322,9 +324,9 @@ const renderPropBlock = (
     const ownerLines = dedupePropLines(["ref?: Ref<Self | null> | undefined;", ...propLines]);
     const extendsList = resolveElementExtends(library, entry, context);
     const extendsClause = extendsList.length === 0 ? "" : ` extends ${extendsList.join(", ")}`;
-    const selfDefault = `${giNamespaceAlias(entry.namespace.name)}.${entry.klass.name}`;
+    const selfDefault = `${giNamespaceAlias(entry.namespace.name)}.${sanitizeTypeIdentifier(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

@@ -66,12 +66,15 @@ const generateMetadata = (library: Library): string => {
 
 const collectIntrinsicElements = (library: Library): IntrinsicElementEntry[] => {
     const entries: IntrinsicElementEntry[] = [];
+    const seen: Set<string> = new Set();
 
     for (const { glibName, klass, namespace } of iterateClassesWithGlibName(library)) {
-        if (!isIntrinsicElementClass(klass, namespace, library)) {
+        if (!isIntrinsicElementClass(klass, namespace, library) || seen.has(glibName)) {
             continue;
         }
 
+        seen.add(glibName);
+
         const sources: GirClass[] = [
             klass,
             ...implementedInterfaces(klass, namespace, library).map((entry) => entry.klass),
@@ -362,9 +365,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/pipeline.ts

@@ -147,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 => {
@@ -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

@@ -1,6 +1,6 @@
 import type { JsxNamespaceFile } from "./jsx/pipeline.js";
 import type { RawFile } from "./store-fs.js";
-import { buildManifest, type StoreOptions, subpathExport, writeStore } from "./store-fs.js";
+import { buildManifest, namespaceBarrel, type StoreOptions, subpathExport, writeStore } from "./store-fs.js";
 
 const writeJsxStore = (
     options: StoreOptions,
@@ -15,8 +15,8 @@ const writeJsxStore = (
     const files = [{ fileName: "metadata.ts", source: metadata }];
 
     for (const { directory, source } of namespaces) {
-        files.push({ fileName: `${directory}/${directory}.tsx`, source });
-        exportsMap[`./${directory}`] = subpathExport(`${directory}/${directory}`);
+        files.push({ fileName: `${directory}/${directory}.tsx`, source }, namespaceBarrel(directory));
+        exportsMap[`./${directory}`] = subpathExport(`${directory}/index`);
     }
 
     writeStore({

package/src/store/resolve-store.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { dirname, join, parse } from "node:path";
+import { dirname, join, parse, relative, sep } from "node:path";
 import type { StoreOptions } from "./store-fs.js";
+import { sweepStagingDirs } from "../staging.js";
 
 /**
  * Where a project's generated stores live, ready to spread into `runCodegen`. `jsx` is null when the
@@ -15,10 +16,20 @@ type ResolvedStore = {
     reactSubexports: string[];
 };
 
-type ResolvedPackage = { dir: string; version: string };
+type ResolvedPackage = { dir: string; nodeModules: string; version: string };
+type StoreConsumer = { name: string; nodeModules: string };
 
 const STORE_DIR = ".gtkx";
 const SCOPE = "@gtkx";
+const STORE_NAMES: string[] = ["gi", "jsx"];
+
+const STORE_CONSUMERS: string[] = [
+    "@gtkx/cli",
+    "@gtkx/components",
+    "@gtkx/css",
+    "@gtkx/react",
+    "@gtkx/testing",
+];
 
 const readManifest = (path: string): { version?: string; exports?: Record<string, unknown> } =>
     JSON.parse(readFileSync(path, "utf8")) as { version?: string; exports?: Record<string, unknown> };
@@ -28,14 +39,14 @@ const subexportNames = (packageDir: string): string[] =>
         .filter((key) => key.startsWith("./") && key !== "./package.json")
         .map((key) => key.slice(2));
 
-const loadPackage = (manifest: string): ResolvedPackage | null => {
+const loadPackage = (manifest: string, nodeModules: string): ResolvedPackage | null => {
     if (!existsSync(manifest)) {
         return null;
     }
 
     const real = realpathSync(manifest);
 
-    return { dir: dirname(real), version: readManifest(real).version ?? "0.0.0" };
+    return { dir: dirname(real), nodeModules, version: readManifest(real).version ?? "0.0.0" };
 };
 
 const nodeModulesChain = function* (projectRoot: string): Generator<string> {
@@ -52,49 +63,153 @@ const nodeModulesChain = function* (projectRoot: string): Generator<string> {
 
 const resolvePackage = (projectRoot: string, packageName: string): ResolvedPackage | null => {
     for (const nodeModules of nodeModulesChain(projectRoot)) {
-        const found = loadPackage(join(nodeModules, packageName, "package.json"));
+        const found = loadPackage(join(nodeModules, packageName, "package.json"), nodeModules);
 
         if (found !== null) {
             return found;
         }
     }
 
-    return loadPackage(join(projectRoot, "packages", packageName.replace(/^@[^/]+\//, ""), "package.json"));
+    const unscoped = packageName.replace(/^@[^/]+\//, "");
+
+    return loadPackage(join(projectRoot, "packages", unscoped, "package.json"), join(projectRoot, "node_modules"));
+};
+
+const isWithin = (parent: string, child: string): boolean => {
+    const path = relative(parent, child);
+
+    return path === "" || (path !== ".." && !path.startsWith(`..${sep}`));
 };
 
+const canImport = (fromNodeModules: string, targetNodeModules: string): boolean =>
+    isWithin(dirname(targetNodeModules), dirname(fromNodeModules));
+
 const storeOptions = (nodeModules: string, name: string, version: string): StoreOptions => ({
     storeDir: join(nodeModules, STORE_DIR, name),
     linkDir: join(nodeModules, SCOPE, name),
     version,
 });
 
+const resolveRuntime = (projectRoot: string): ResolvedPackage => {
+    const runtime = resolvePackage(projectRoot, "@gtkx/runtime");
+
+    if (runtime === null) {
+        throw new Error(`Cannot resolve @gtkx/runtime from ${projectRoot}; is it installed?`);
+    }
+
+    return runtime;
+};
+
+const storeNodeModules = (runtime: ResolvedPackage, react: ResolvedPackage | null): string => {
+    if (react !== null && canImport(react.nodeModules, runtime.nodeModules)) {
+        return react.nodeModules;
+    }
+
+    return runtime.nodeModules;
+};
+
+const findUnreachableConsumer = (projectRoot: string, nodeModules: string): StoreConsumer | null => {
+    for (const name of STORE_CONSUMERS) {
+        const consumer = resolvePackage(projectRoot, name);
+
+        if (consumer !== null && !canImport(consumer.nodeModules, nodeModules)) {
+            return { name, nodeModules: consumer.nodeModules };
+        }
+    }
+
+    return null;
+};
+
+const unreachableConsumerMessage = (consumer: StoreConsumer, nodeModules: string): string =>
+    `Cannot write the generated store to ${nodeModules}: ${consumer.name} is installed in ` +
+    `${consumer.nodeModules}, above it, so that copy can never import the generated @gtkx/gi. Install every ` +
+    "@gtkx package in one node_modules, then run gtkx codegen again.";
+
+const checkConsumers = (projectRoot: string, nodeModules: string): void => {
+    const consumer = findUnreachableConsumer(projectRoot, nodeModules);
+
+    if (consumer !== null) {
+        throw new Error(unreachableConsumerMessage(consumer, nodeModules));
+    }
+};
+
+const jsxOptions = (react: ResolvedPackage | null, nodeModules: string): StoreOptions | null =>
+    react === null ? null : storeOptions(nodeModules, "jsx", react.version);
+
+const getReactSubexports = (react: ResolvedPackage | null): string[] =>
+    react === null ? [] : subexportNames(react.dir);
+
+const storePaths = (nodeModules: string): string[] =>
+    STORE_NAMES.flatMap((name) => [join(nodeModules, STORE_DIR, name), join(nodeModules, SCOPE, name)]);
+
+const findStoreNodeModules = (projectRoot: string): string | null => {
+    const runtime = resolvePackage(projectRoot, "@gtkx/runtime");
+
+    if (runtime === null) {
+        return null;
+    }
+
+    return storeNodeModules(runtime, resolvePackage(projectRoot, "@gtkx/react"));
+};
+
+const getShadowingStorePaths = (projectRoot: string): string[] => {
+    const nodeModules = join(projectRoot, "node_modules");
+    const anchored = findStoreNodeModules(projectRoot);
+
+    if (anchored === null || anchored === nodeModules) {
+        return [];
+    }
+
+    return storePaths(nodeModules);
+};
+
+const stagingRoots = (projectRoot: string): string[] => {
+    const nodeModules = join(projectRoot, "node_modules");
+    const anchored = findStoreNodeModules(projectRoot);
+
+    return anchored === null || anchored === nodeModules ? [nodeModules] : [nodeModules, anchored];
+};
+
+const sweepProjectStaging = (projectRoot: string): void => {
+    for (const nodeModules of stagingRoots(projectRoot)) {
+        for (const name of STORE_NAMES) {
+            sweepStagingDirs(join(nodeModules, STORE_DIR, name));
+        }
+    }
+};
+
 /**
  * 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.
  *
+ * Both stores go in one `node_modules`, found by walking the project's `node_modules` chain upwards:
+ * the one `@gtkx/react` resolves from, or `@gtkx/runtime`'s when no React is installed. That is the
+ * project's own directory when it installs those packages itself, and the workspace root when npm or
+ * yarn hoisted them there. Keeping the pair together is what lets the jsx store import the gi store, and
+ * anchoring them where the `@gtkx` packages sit is what lets `@gtkx/react`, the CLI, and the project's
+ * sources all reach the bindings. A package manager that hoists therefore gives every project sharing
+ * that `node_modules` one shared store.
+ *
  * 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`.
+ * @param projectRoot Directory holding the project's `package.json`, whose `node_modules` chain is walked.
  * @returns The store locations and the React subexports that shape the jsx store.
- * @throws If `@gtkx/runtime` cannot be resolved from the project.
+ * @throws If `@gtkx/runtime` cannot be resolved from the project, or a `@gtkx` package that imports the
+ * bindings is installed above the `node_modules` the stores would go in, since it could not reach them.
  */
 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 runtime = resolveRuntime(projectRoot);
     const react = resolvePackage(projectRoot, "@gtkx/react");
-    const nodeModules = join(projectRoot, "node_modules");
+    const nodeModules = storeNodeModules(runtime, react);
+    checkConsumers(projectRoot, nodeModules);
 
     return {
         gi: storeOptions(nodeModules, "gi", runtime.version),
-        jsx: react === null ? null : storeOptions(nodeModules, "jsx", react.version),
-        reactSubexports: react === null ? [] : subexportNames(react.dir),
+        jsx: jsxOptions(react, nodeModules),
+        reactSubexports: getReactSubexports(react),
     };
 };
 
-export { resolveStore, type ResolvedStore };
+export { getShadowingStorePaths, resolveStore, sweepProjectStaging, type ResolvedStore };