hadars 0.2.2-rc.1 → 0.3.0

package/dist/index.cjs

@@ -33,6 +33,7 @@ __export(index_exports, {
   HadarsHead: () => Head,
   initServerDataCache: () => initServerDataCache,
   loadModule: () => loadModule,
+  useGraphQL: () => useGraphQL,
   useServerData: () => useServerData
 });
 module.exports = __toCommonJS(index_exports);
@@ -296,6 +297,32 @@ function useServerData(key, fn) {
   if (existing.status === "rejected") throw existing.reason;
   return existing.value;
 }
+function toCacheKey(doc) {
+  if (typeof doc === "string") return doc.trim();
+  for (const def of doc?.definitions ?? []) {
+    if (def.kind === "OperationDefinition" && def.name?.value) {
+      return `op:${def.name.value}`;
+    }
+  }
+  return JSON.stringify(doc?.definitions ?? doc);
+}
+function useGraphQL(query, variables) {
+  const key = ["__gql", toCacheKey(query), JSON.stringify(variables ?? {})];
+  return useServerData(key, async () => {
+    const executor = globalThis.__hadarsGraphQL;
+    if (!executor) {
+      throw new Error(
+        "[hadars] useGraphQL: no GraphQL executor is available for this request. Make sure you have `sources` or a `graphql` executor configured in hadars.config.ts."
+      );
+    }
+    const result = await executor(query, variables);
+    if (result.errors?.length) {
+      const messages = result.errors.map((e) => e.message).join(", ");
+      throw new Error(`[hadars] GraphQL error: ${messages}`);
+    }
+    return result;
+  });
+}
 var Head = import_react.default.memo(({ children, status }) => {
   const ctx = getCtx();
   if (!ctx) return null;
@@ -309,7 +336,8 @@ var Head = import_react.default.memo(({ children, status }) => {
     const childProps = child.props;
     switch (childType) {
       case "title": {
-        setTitle(childProps["children"]);
+        const raw = childProps["children"];
+        setTitle(Array.isArray(raw) ? raw.join("") : String(raw ?? ""));
         return;
       }
       case "meta": {
@@ -355,5 +383,6 @@ function loadModule(path) {
   HadarsHead,
   initServerDataCache,
   loadModule,
+  useGraphQL,
   useServerData
 });

package/dist/index.d.cts

@@ -1,4 +1,5 @@
-export { G as GraphQLExecutor, b as HadarsApp, H as HadarsEntryModule, c as HadarsGetClientProps, d as HadarsGetFinalProps, e as HadarsGetInitialProps, a as HadarsOptions, f as HadarsProps, g as HadarsRequest, h as HadarsSourceEntry, i as HadarsStaticContext } from './hadars-mKu5txjW.cjs';
+import { b as HadarsDocumentNode } from './hadars-CSWWhlQC.cjs';
+export { G as GraphQLExecutor, c as HadarsApp, H as HadarsEntryModule, d as HadarsGetClientProps, e as HadarsGetFinalProps, f as HadarsGetInitialProps, a as HadarsOptions, g as HadarsProps, h as HadarsRequest, i as HadarsSourceEntry, j as HadarsStaticContext } from './hadars-CSWWhlQC.cjs';
 import React from 'react';
 
 /** Call this before hydrating to seed the client cache from the server's data.
@@ -32,6 +33,32 @@ declare function initServerDataCache(data: Record<string, unknown>): void;
  * if (!user) return null; // undefined while pending on the first SSR pass
  */
 declare function useServerData<T>(key: string | string[], fn: () => Promise<T> | T): T | undefined;
+/**
+ * Execute a GraphQL query server-side and return the result.
+ *
+ * Wraps `useServerData` — on the client the pre-resolved value is read from
+ * the hydration cache. During client-side navigation hadars automatically
+ * fires a data-only request to the server so the query re-executes there.
+ *
+ * Throws if the executor returns GraphQL errors, so the page is correctly
+ * marked as failed during `hadars export static`.
+ *
+ * ```tsx
+ * // Typed via codegen document — TData and TVariables are inferred:
+ * const result = useGraphQL(GetPostDocument, { slug });
+ * const post = result?.data?.blogPost; // fully typed
+ *
+ * // Plain string query — untyped:
+ * const result = useGraphQL(`{ allBlogPost { slug title } }`);
+ * if (!result) return null; // undefined while pending on first SSR pass
+ * ```
+ */
+declare function useGraphQL<TData, TVariables extends Record<string, unknown>>(query: HadarsDocumentNode<TData, TVariables>, variables?: TVariables): {
+    data?: TData;
+} | undefined;
+declare function useGraphQL(query: string, variables?: Record<string, unknown>): {
+    data?: Record<string, unknown>;
+} | undefined;
 declare const Head: React.FC<{
     children?: React.ReactNode;
     status?: number;
@@ -57,4 +84,4 @@ declare const Head: React.FC<{
  */
 declare function loadModule<T = any>(path: string): Promise<T>;
 
-export { Head as HadarsHead, initServerDataCache, loadModule, useServerData };
+export { HadarsDocumentNode, Head as HadarsHead, initServerDataCache, loadModule, useGraphQL, useServerData };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { G as GraphQLExecutor, b as HadarsApp, H as HadarsEntryModule, c as HadarsGetClientProps, d as HadarsGetFinalProps, e as HadarsGetInitialProps, a as HadarsOptions, f as HadarsProps, g as HadarsRequest, h as HadarsSourceEntry, i as HadarsStaticContext } from './hadars-mKu5txjW.js';
+import { b as HadarsDocumentNode } from './hadars-CSWWhlQC.js';
+export { G as GraphQLExecutor, c as HadarsApp, H as HadarsEntryModule, d as HadarsGetClientProps, e as HadarsGetFinalProps, f as HadarsGetInitialProps, a as HadarsOptions, g as HadarsProps, h as HadarsRequest, i as HadarsSourceEntry, j as HadarsStaticContext } from './hadars-CSWWhlQC.js';
 import React from 'react';
 
 /** Call this before hydrating to seed the client cache from the server's data.
@@ -32,6 +33,32 @@ declare function initServerDataCache(data: Record<string, unknown>): void;
  * if (!user) return null; // undefined while pending on the first SSR pass
  */
 declare function useServerData<T>(key: string | string[], fn: () => Promise<T> | T): T | undefined;
+/**
+ * Execute a GraphQL query server-side and return the result.
+ *
+ * Wraps `useServerData` — on the client the pre-resolved value is read from
+ * the hydration cache. During client-side navigation hadars automatically
+ * fires a data-only request to the server so the query re-executes there.
+ *
+ * Throws if the executor returns GraphQL errors, so the page is correctly
+ * marked as failed during `hadars export static`.
+ *
+ * ```tsx
+ * // Typed via codegen document — TData and TVariables are inferred:
+ * const result = useGraphQL(GetPostDocument, { slug });
+ * const post = result?.data?.blogPost; // fully typed
+ *
+ * // Plain string query — untyped:
+ * const result = useGraphQL(`{ allBlogPost { slug title } }`);
+ * if (!result) return null; // undefined while pending on first SSR pass
+ * ```
+ */
+declare function useGraphQL<TData, TVariables extends Record<string, unknown>>(query: HadarsDocumentNode<TData, TVariables>, variables?: TVariables): {
+    data?: TData;
+} | undefined;
+declare function useGraphQL(query: string, variables?: Record<string, unknown>): {
+    data?: Record<string, unknown>;
+} | undefined;
 declare const Head: React.FC<{
     children?: React.ReactNode;
     status?: number;
@@ -57,4 +84,4 @@ declare const Head: React.FC<{
  */
 declare function loadModule<T = any>(path: string): Promise<T>;
 
-export { Head as HadarsHead, initServerDataCache, loadModule, useServerData };
+export { HadarsDocumentNode, Head as HadarsHead, initServerDataCache, loadModule, useGraphQL, useServerData };

package/dist/index.js

@@ -257,6 +257,32 @@ function useServerData(key, fn) {
   if (existing.status === "rejected") throw existing.reason;
   return existing.value;
 }
+function toCacheKey(doc) {
+  if (typeof doc === "string") return doc.trim();
+  for (const def of doc?.definitions ?? []) {
+    if (def.kind === "OperationDefinition" && def.name?.value) {
+      return `op:${def.name.value}`;
+    }
+  }
+  return JSON.stringify(doc?.definitions ?? doc);
+}
+function useGraphQL(query, variables) {
+  const key = ["__gql", toCacheKey(query), JSON.stringify(variables ?? {})];
+  return useServerData(key, async () => {
+    const executor = globalThis.__hadarsGraphQL;
+    if (!executor) {
+      throw new Error(
+        "[hadars] useGraphQL: no GraphQL executor is available for this request. Make sure you have `sources` or a `graphql` executor configured in hadars.config.ts."
+      );
+    }
+    const result = await executor(query, variables);
+    if (result.errors?.length) {
+      const messages = result.errors.map((e) => e.message).join(", ");
+      throw new Error(`[hadars] GraphQL error: ${messages}`);
+    }
+    return result;
+  });
+}
 var Head = React.memo(({ children, status }) => {
   const ctx = getCtx();
   if (!ctx) return null;
@@ -270,7 +296,8 @@ var Head = React.memo(({ children, status }) => {
     const childProps = child.props;
     switch (childType) {
       case "title": {
-        setTitle(childProps["children"]);
+        const raw = childProps["children"];
+        setTitle(Array.isArray(raw) ? raw.join("") : String(raw ?? ""));
         return;
       }
       case "meta": {
@@ -315,5 +342,6 @@ export {
   Head as HadarsHead,
   initServerDataCache,
   loadModule,
+  useGraphQL,
   useServerData
 };

package/dist/lambda.d.cts

@@ -1,4 +1,4 @@
-import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-mKu5txjW.cjs';
+import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-CSWWhlQC.cjs';
 
 /**
  * AWS Lambda adapter for hadars.

package/dist/lambda.d.ts

@@ -1,4 +1,4 @@
-import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-mKu5txjW.js';
+import { H as HadarsEntryModule, a as HadarsOptions } from './hadars-CSWWhlQC.js';
 
 /**
  * AWS Lambda adapter for hadars.

package/dist/utils/Head.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import type { AppHead, AppUnsuspend, LinkProps, MetaProps, ScriptProps, StyleProps } from '../types/hadars'
+import type { AppHead, AppUnsuspend, HadarsDocumentNode, LinkProps, MetaProps, ScriptProps, StyleProps } from '../types/hadars'
 
 interface InnerContext {
     setTitle: (title: string) => void;
@@ -357,6 +357,98 @@ export function useServerData<T>(key: string | string[], fn: () => Promise<T> |
 }
 
 
+// ── useGraphQL ────────────────────────────────────────────────────────────────
+//
+// Execute a GraphQL query during SSR via the hadars data layer. The executor
+// is stored in globalThis.__hadarsGraphQL by the framework before each render.
+// On the client, useServerData handles hydration + client-side navigation.
+
+/**
+ * Derive a stable cache key string from a query argument.
+ * For string queries the key is the trimmed query string.
+ * For document nodes we use the operation name when available (fast, concise)
+ * and fall back to stringifying the definitions (always stable).
+ * The key is ONLY used for cache lookup — the original document is passed to
+ * the executor so it can call print() itself.
+ */
+function toCacheKey(doc: any): string {
+    if (typeof doc === 'string') return doc.trim();
+    // Use the operation name for named operations — compact and stable.
+    for (const def of doc?.definitions ?? []) {
+        if (def.kind === 'OperationDefinition' && def.name?.value) {
+            return `op:${def.name.value}`;
+        }
+    }
+    // Anonymous operation — fall back to stringifying definitions.
+    return JSON.stringify(doc?.definitions ?? doc);
+}
+
+/**
+ * Execute a GraphQL query server-side and return the result.
+ *
+ * Wraps `useServerData` — on the client the pre-resolved value is read from
+ * the hydration cache. During client-side navigation hadars automatically
+ * fires a data-only request to the server so the query re-executes there.
+ *
+ * Throws if the executor returns GraphQL errors, so the page is correctly
+ * marked as failed during `hadars export static`.
+ *
+ * ```tsx
+ * // Typed via codegen document — TData and TVariables are inferred:
+ * const result = useGraphQL(GetPostDocument, { slug });
+ * const post = result?.data?.blogPost; // fully typed
+ *
+ * // Plain string query — untyped:
+ * const result = useGraphQL(`{ allBlogPost { slug title } }`);
+ * if (!result) return null; // undefined while pending on first SSR pass
+ * ```
+ */
+// Overload 1: TypedDocumentNode — TData and TVariables are inferred from the document.
+export function useGraphQL<
+    TData,
+    TVariables extends Record<string, unknown>,
+>(
+    query: HadarsDocumentNode<TData, TVariables>,
+    variables?: TVariables,
+): { data?: TData } | undefined;
+// Overload 2: plain string query — untyped result.
+export function useGraphQL(
+    query: string,
+    variables?: Record<string, unknown>,
+): { data?: Record<string, unknown> } | undefined;
+// Implementation
+export function useGraphQL(
+    query: string | HadarsDocumentNode<unknown, Record<string, unknown>>,
+    variables?: Record<string, unknown>,
+): { data?: unknown } | undefined {
+    const key = ['__gql', toCacheKey(query), JSON.stringify(variables ?? {})];
+
+    return useServerData(key, async () => {
+        const executor: ((q: any, v?: Record<string, unknown>) => Promise<any>) | undefined =
+            (globalThis as any).__hadarsGraphQL;
+
+        if (!executor) {
+            throw new Error(
+                '[hadars] useGraphQL: no GraphQL executor is available for this request. ' +
+                'Make sure you have `sources` or a `graphql` executor configured in hadars.config.ts.',
+            );
+        }
+
+        // Pass the original query (string or document object) — the executor
+        // calls print() itself so codegen documents without loc.source.body work.
+        const result = await executor(query, variables);
+
+        if (result.errors?.length) {
+            const messages = result.errors.map((e: { message: string }) => e.message).join(', ');
+            throw new Error(`[hadars] GraphQL error: ${messages}`);
+        }
+
+        return result;
+    });
+}
+
+// ── HadarsHead ────────────────────────────────────────────────────────────────
+
 export const Head: React.FC<{
     children?: React.ReactNode;
     status?: number;
@@ -381,7 +473,8 @@ export const Head: React.FC<{
 
         switch ( childType ) {
             case 'title': {
-                setTitle(childProps['children'] as string);
+                const raw = childProps['children'];
+                setTitle(Array.isArray(raw) ? raw.join('') : String(raw ?? ''));
                 return;
             }
             case 'meta': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hadars",
-  "version": "0.2.2-rc.1",
+  "version": "0.3.0",
   "description": "Minimal SSR framework for React — rspack, HMR, TypeScript, Bun/Node/Deno",
   "module": "./dist/index.js",
   "type": "module",

package/src/build.ts

@@ -546,6 +546,9 @@ export const dev = async (options: HadarsRuntimeOptions) => {
                 getFinalProps,
             } = (await import(importPath)) as HadarsEntryModule<any>;
 
+            // Expose the executor globally so useGraphQL() in components can reach it.
+            (globalThis as any).__hadarsGraphQL = devStaticCtx?.graphql;
+
             const { head, status, getAppBody, finalize } = await getReactResponse(request, {
                 document: {
                     body: Component as React.FC<HadarsProps<object>>,

package/src/index.tsx

@@ -10,8 +10,9 @@ export type {
     HadarsStaticContext,
     GraphQLExecutor,
     HadarsSourceEntry,
+    HadarsDocumentNode,
 } from "./types/hadars";
-export { Head as HadarsHead, useServerData, initServerDataCache } from './utils/Head';
+export { Head as HadarsHead, useServerData, useGraphQL, initServerDataCache } from './utils/Head';
 
 /**
  * Dynamically loads a module with target-aware behaviour:

package/src/source/context.ts

@@ -65,7 +65,7 @@ export function makeGatsbyContext(
         set: (key, value) => { cacheMap.set(key, value); return Promise.resolve(); },
     };
 
-    const reporter: GatsbyReporter = {
+    const reporter: GatsbyReporter & Record<string, unknown> = {
         info:    (msg) => console.log(`[${pluginName}] ${msg}`),
         warn:    (msg) => console.warn(`[${pluginName}] WARN: ${msg}`),
         error:   (msg, err) => console.error(`[${pluginName}] ERROR: ${msg}`, err ?? ''),
@@ -79,14 +79,14 @@ export function makeGatsbyContext(
         setErrorMap: () => {},
         log:         (msg: string) => console.log(`[${pluginName}] ${msg}`),
         success:     (msg: string) => console.log(`[${pluginName}] ✓ ${msg}`),
-    } as any;
+    };
 
     const actions: GatsbyActions = {
         createNode: (node) => store.createNode(node),
         deleteNode: ({ id }) => {
-            // NodeStore doesn't expose delete — it's rarely needed by source plugins
-            // on first run, so we silently no-op. A full implementation would add
-            // store.deleteNode().
+            // NodeStore doesn't implement delete — it's rarely needed on a first run.
+            // Warn so plugin authors know the operation was ignored.
+            console.warn(`[${pluginName}] deleteNode("${id}") called but is not supported by hadars — node will remain in the store.`);
         },
         touchNode: () => { /* no-op — only relevant for Gatsby's caching layer */ },
     };

package/src/source/graphiql.ts

@@ -49,7 +49,12 @@ export function createGraphiqlHandler(
     executor: GraphQLExecutor,
 ): (req: Request) => Promise<Response | undefined> {
     return async (req: Request): Promise<Response | undefined> => {
-        const url = new URL(req.url);
+        let url: URL;
+        try {
+            url = new URL(req.url);
+        } catch {
+            return undefined;
+        }
         if (url.pathname !== GRAPHQL_PATH) return undefined;
 
         // GET — serve GraphiQL IDE
@@ -71,8 +76,8 @@ export function createGraphiqlHandler(
                 });
             }
 
-            if (!body.query) {
-                return new Response(JSON.stringify({ errors: [{ message: 'Missing "query" field' }] }), {
+            if (typeof body.query !== 'string' || !body.query.trim()) {
+                return new Response(JSON.stringify({ errors: [{ message: 'Missing or invalid "query" field — must be a non-empty string' }] }), {
                     status: 400,
                     headers: { 'Content-Type': 'application/json' },
                 });

package/src/source/inference.ts

@@ -43,6 +43,8 @@ function inferFieldShape(value: unknown, seenTypes: Set<string>): FieldShape {
 // ── Schema string builder ──────────────────────────────────────────────────────
 
 const INTERNAL_FIELDS = new Set(['id', 'internal', '__typename', 'parent', 'children']);
+/** GraphQL spec reserves all names beginning with __ for introspection. */
+const isReservedFieldName = (name: string) => name.startsWith('__');
 
 /** Scalar GraphQL types that are safe to use as lookup filter arguments. */
 const FILTERABLE_SCALARS = new Set(['String', 'Int', 'Float', 'Boolean', 'ID']);
@@ -59,7 +61,7 @@ function buildTypeFields(nodes: readonly Record<string, unknown>[]): InferredFie
 
     for (const node of nodes) {
         for (const [key, val] of Object.entries(node)) {
-            if (INTERNAL_FIELDS.has(key)) continue;
+            if (INTERNAL_FIELDS.has(key) || isReservedFieldName(key)) continue;
             if (fieldMap.has(key)) continue;
             const { type } = inferFieldShape(val, new Set());
             fieldMap.set(key, {
@@ -106,17 +108,14 @@ function buildSingleArgs(fields: InferredField[]): string {
 // ── Public API ─────────────────────────────────────────────────────────────────
 
 /**
- * Build a GraphQL executor backed by the node store.
- *
- * Returns null if graphql-js is not installed — in that case the caller should
- * surface a clear error message asking the user to install `graphql`.
+ * Load graphql-js from the user's project and build a schema + SDL from the
+ * node store. Returns null if graphql-js is not installed.
  */
-export async function buildSchemaExecutor(
-    store: NodeStore,
-): Promise<GraphQLExecutor | null> {
-    // graphql is an optional peer dependency installed in the user's project,
-    // not in hadars itself. Resolve it from process.cwd() so Node.js finds it
-    // in the user's node_modules rather than the CLI's own node_modules.
+async function loadAndBuildSchema(store: NodeStore): Promise<{
+    schema: any;
+    sdl: string;
+    gql: any;
+} | null> {
     let gql: any;
     try {
         const { createRequire } = await import('node:module');
@@ -127,16 +126,15 @@ export async function buildSchemaExecutor(
         return null;
     }
 
-    const { buildSchema, graphql } = gql;
-
+    const { buildSchema, printSchema, print } = gql;
     const types = store.getTypes();
+
     if (types.length === 0) {
-        // Empty store — return a no-op executor with a dummy schema
-        const schema = buildSchema('type Query { _empty: String }');
-        return (query, variables) => graphql({ schema, source: query, variableValues: variables });
+        const rawSdl = 'type Query { _empty: String }';
+        return { schema: buildSchema(rawSdl), sdl: rawSdl, gql };
     }
 
-    // Infer field shapes once per type — reused for both the SDL and resolvers.
+    // Infer field shapes once per type — reused for SDL, resolvers, and args.
     const typeFields = new Map(
         types.map(typeName => {
             const nodes = store.getNodesByType(typeName) as Record<string, unknown>[];
@@ -157,18 +155,50 @@ export async function buildSchemaExecutor(
         ].join('\n');
     });
 
-    const sdl = [
+    const rawSdl = [
         ...typeSDLs,
         `type Query {\n${queryFields.join('\n')}\n}`,
     ].join('\n\n');
 
     let schema: any;
     try {
-        schema = buildSchema(sdl);
+        schema = buildSchema(rawSdl);
     } catch (err) {
         throw new Error(`[hadars] Failed to build GraphQL schema from node store: ${(err as Error).message}`);
     }
 
+    return { schema, sdl: printSchema(schema), gql };
+}
+
+/**
+ * Build a GraphQL executor backed by the node store.
+ *
+ * Returns null if graphql-js is not installed — in that case the caller should
+ * surface a clear error message asking the user to install `graphql`.
+ */
+/**
+ * Normalise a query argument to a string.
+ * Accepts either a plain query string or a TypedDocumentNode / codegen document object.
+ */
+function toQueryString(query: unknown, print: (doc: any) => string): string {
+    return typeof query === 'string' ? query : print(query);
+}
+
+export async function buildSchemaExecutor(
+    store: NodeStore,
+): Promise<GraphQLExecutor | null> {
+    const built = await loadAndBuildSchema(store);
+    if (!built) return null;
+
+    const { schema, gql } = built;
+    const { graphql, print } = gql;
+    const types = store.getTypes();
+
+    if (types.length === 0) {
+        return (query, variables) =>
+            graphql({ schema, source: toQueryString(query, print), variableValues: variables });
+    }
+
     // Build root resolver map
     const rootValue: Record<string, unknown> = {};
     for (const typeName of types) {
@@ -184,5 +214,47 @@ export async function buildSchemaExecutor(
     }
 
     return (query, variables) =>
-        graphql({ schema, rootValue, source: query, variableValues: variables }) as any;
+        graphql({ schema, rootValue, source: toQueryString(query, print), variableValues: variables }) as any;
+}
+
+/**
+ * Return the inferred GraphQL schema as a SDL string suitable for writing to a
+ * `schema.graphql` file and consuming with graphql-codegen or gql.tada.
+ *
+ * Returns null if graphql-js is not installed in the user's project.
+ */
+export async function buildSchemaSDL(store: NodeStore): Promise<string | null> {
+    const built = await loadAndBuildSchema(store);
+    return built?.sdl ?? null;
+}
+
+/**
+ * Introspect a custom GraphQL executor and return its schema as SDL.
+ * Uses the standard introspection query so the executor doesn't need to know
+ * about hadars internals.
+ *
+ * Returns null if graphql-js is not installed in the user's project.
+ */
+export async function introspectExecutorSDL(
+    executor: GraphQLExecutor,
+): Promise<string | null> {
+    let gql: any;
+    try {
+        const { createRequire } = await import('node:module');
+        const projectRequire = createRequire(process.cwd() + '/package.json');
+        const graphqlPath = projectRequire.resolve('graphql');
+        gql = await import(graphqlPath);
+    } catch {
+        return null;
+    }
+
+    const { getIntrospectionQuery, buildClientSchema, printSchema } = gql;
+    const result = await executor(getIntrospectionQuery());
+    if (result.errors?.length) {
+        throw new Error(`[hadars] Introspection failed: ${result.errors[0].message}`);
+    }
+    if (!result.data) {
+        throw new Error('[hadars] Introspection returned no data');
+    }
+    return printSchema(buildClientSchema(result.data));
 }

package/src/source/runner.ts

@@ -19,10 +19,13 @@ import type { HadarsSourceEntry } from '../types/hadars';
 const SETTLE_IDLE_MS = 300;
 /** Hard timeout — give up waiting after this many ms. */
 const SETTLE_TIMEOUT_MS = 10_000;
+/** Timeout for a single sourceNodes() call before we give up waiting. */
+const SOURCE_NODES_TIMEOUT_MS = 30_000;
 
 /**
  * Wait until no createNode call has been received for SETTLE_IDLE_MS,
  * or until SETTLE_TIMEOUT_MS elapses, whichever comes first.
+ * Timers are unref()ed so they don't keep the process alive artificially.
  */
 function waitForSettle(getLastNodeTime: () => number): Promise<void> {
     return new Promise(resolve => {
@@ -32,10 +35,24 @@ function waitForSettle(getLastNodeTime: () => number): Promise<void> {
             if (idle >= SETTLE_IDLE_MS || Date.now() >= deadline) {
                 resolve();
             } else {
-                setTimeout(check, 50);
+                const t = setTimeout(check, 50);
+                t.unref?.();
             }
         };
-        setTimeout(check, SETTLE_IDLE_MS);
+        const t = setTimeout(check, SETTLE_IDLE_MS);
+        t.unref?.();
+    });
+}
+
+/**
+ * Run a promise with a hard timeout. Rejects with a clear message if the
+ * deadline is exceeded, but does not cancel the original promise.
+ */
+function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+    return new Promise((resolve, reject) => {
+        const t = setTimeout(() => reject(new Error(`[hadars] "${label}" timed out after ${ms}ms`)), ms);
+        t.unref?.();
+        promise.then(resolve, reject).finally(() => clearTimeout(t));
     });
 }
 
@@ -93,11 +110,18 @@ export async function runSources(
         const ctx = makeGatsbyContext(trackingStore, pluginName, options, emitter);
 
         try {
-            await mod.sourceNodes(ctx, options);
+            await withTimeout(
+                Promise.resolve(mod.sourceNodes(ctx, options)),
+                SOURCE_NODES_TIMEOUT_MS,
+                `${pluginName} sourceNodes`,
+            );
         } catch (err) {
-            throw new Error(
-                `[hadars] source plugin "${pluginName}" threw during sourceNodes: ${(err as Error).message}`,
+            const cause = err instanceof Error ? err : new Error(String(err));
+            const wrapped = new Error(
+                `[hadars] source plugin "${pluginName}" threw during sourceNodes: ${cause.message}`,
             );
+            wrapped.cause = cause;
+            throw wrapped;
         }
 
         // Phase 1: wait for async initial-scan nodes (e.g. chokidar ready → createFileNode).

package/src/source/store.ts

@@ -22,6 +22,8 @@ export class NodeStore {
     private byType = new Map<string, HadarsNode[]>();
 
     createNode(node: HadarsNode): void {
+        if (!node.id) throw new Error('[hadars] createNode: node.id must be a non-empty string');
+        if (!node.internal?.type) throw new Error('[hadars] createNode: node.internal.type must be a non-empty string');
         this.byId.set(node.id, node);
         const list = this.byType.get(node.internal.type) ?? [];
         // Replace existing node with same id if present

package/src/static.ts

@@ -51,6 +51,9 @@ export async function renderStaticSite(opts: {
         try {
             const req = parseRequest(new Request('http://localhost' + urlPath));
 
+            // Expose the executor globally so useGraphQL() in components can reach it.
+            (globalThis as any).__hadarsGraphQL = staticCtx.graphql;
+
             const { head, getAppBody, finalize } = await getReactResponse(req, {
                 document: {
                     body:          ssrModule.default as any,