docs: add sandbox and ensv2readiness

AGENTS.md

@@ -43,6 +43,7 @@ Runnable commands for validating changes; lint and format with Biome.
 - Lint and format: `pnpm lint` (fixes where applicable); CI lint: `pnpm lint:ci`
 - Type checking: `pnpm typecheck` (runs typecheck in all workspaces)
   - Always use `pnpm -F <package-name> typecheck`, never call `tsc` or `tsgo` directly
+- Omnigraph example sample responses (docs): after changing SDK Omnigraph example queries/variables in `packages/ensnode-sdk` or when refreshing live JSON shown in the docs Omnigraph examples, run `pnpm -F @docs/ensnode omnigraph-examples:refresh-responses` (requires `curl`, network). Updates `docs/ensnode.io/src/data/omnigraph-examples/responses.json`.
 
 ## Testing
 

apps/ensadmin/package.json

@@ -23,9 +23,9 @@
   },
   "dependencies": {
     "@ensnode/datasources": "workspace:*",
-    "@ensnode/ensnode-sdk": "workspace:*",
+    "@ensnode/ensnode-sdk": "0.0.0-preview-fix-sha-89c022b-20260518142147",
     "@ensnode/scalar-react": "workspace:*",
-    "enssdk": "workspace:*",
+    "enssdk": "0.0.0-preview-fix-sha-89c022b-20260518142147",
     "@formkit/auto-animate": "^0.9.0",
     "@graphiql/plugin-explorer": "5.1.1",
     "@graphiql/react": "0.37.1",

apps/ensapi/src/omnigraph-api/schema/example-queries.integration.test.ts

@@ -2,19 +2,20 @@ import { type OperationDefinitionNode, parse } from "graphql";
 import { describe, expect, it } from "vitest";
 
 import { ENSNamespaceIds } from "@ensnode/datasources";
+import { getNamespaceSpecificValue } from "@ensnode/ensnode-sdk";
 import { GRAPHQL_API_EXAMPLE_QUERIES } from "@ensnode/ensnode-sdk/internal";
 
 import { request } from "@/test/integration/graphql-utils";
 
 const namespace = ENSNamespaceIds.EnsTestEnv;
 
-const EXAMPLE_QUERY_TEST_CASES = GRAPHQL_API_EXAMPLE_QUERIES.map((entry, i) => {
+const EXAMPLE_QUERY_TEST_CASES = GRAPHQL_API_EXAMPLE_QUERIES.map((entry) => {
   const document = parse(entry.query);
   const operation = document.definitions.find(
     (d): d is OperationDefinitionNode => d.kind === "OperationDefinition",
   );
-  const name = operation?.name?.value ?? `Query #${i}`;
-  const variables = entry.variables[namespace] ?? entry.variables.default;
+  const name = operation?.name?.value ?? entry.id;
+  const variables = getNamespaceSpecificValue(namespace, entry.variables);
   return { name, query: entry.query, variables };
 });
 

apps/ensapi/src/omnigraph-api/schema/example-queries.test.ts

@@ -5,8 +5,8 @@ import { GRAPHQL_API_EXAMPLE_QUERIES } from "@ensnode/ensnode-sdk/internal";
 
 describe("Example Queries", () => {
   it.each(
-    GRAPHQL_API_EXAMPLE_QUERIES.map((entry, i) => ({
-      name: `Query #${i}`,
+    GRAPHQL_API_EXAMPLE_QUERIES.map((entry) => ({
+      name: entry.id,
       query: entry.query,
     })),
   )("$name parses as valid GraphQL", ({ query }) => {

docs/ensnode.io/astro.config.mjs

@@ -1,3 +1,5 @@
+import { fileURLToPath } from "node:url";
+
 import mdx from "@astrojs/mdx";
 import react from "@astrojs/react";
 import tailwindcss from "@tailwindcss/vite";
@@ -13,6 +15,18 @@ export default defineConfig({
   trailingSlash: "never",
   integrations: [mermaid(), starlight(), sitemap(), react(), mdx(), icon()],
   vite: {
+    resolve: {
+      alias: {
+        "@assets": fileURLToPath(new URL("./src/assets", import.meta.url)),
+        "@components": fileURLToPath(new URL("./src/components", import.meta.url)),
+        "@content": fileURLToPath(new URL("./src/content", import.meta.url)),
+        "@data": fileURLToPath(new URL("./src/data", import.meta.url)),
+        "@lib": fileURLToPath(new URL("./src/lib", import.meta.url)),
+        "@scripts": fileURLToPath(new URL("./src/scripts", import.meta.url)),
+        "@styles": fileURLToPath(new URL("./src/styles", import.meta.url)),
+        "@workspace": fileURLToPath(new URL("../..", import.meta.url)),
+      },
+    },
     ssr: {
       noExternal: ["@namehash/namehash-ui"],
     },

docs/ensnode.io/config/integrations/llms-txt.ts

@@ -0,0 +1,20 @@
+import starlightLlmsTxt from "starlight-llms-txt";
+
+/**
+ * `starlight-llms-txt` renders each docs entry for `/llms-full.txt` and `/llms-small.txt` through
+ * an Astro container that only registers the MDX SSR renderer, not React. MDX pages that import
+ * `.tsx` islands must be omitted from those exports or `astro build` fails with `NoMatchingRenderer`.
+ *
+ * Patterns use micromatch against each entry's `id` in the Starlight `docs` collection (paths are
+ * relative to `src/content/docs/`).
+ *
+ * The Interactive example imports a React playground and cannot be rendered by `starlight-llms-txt`.
+ * The Schema Reference imports a React playground and cannot be rendered by `starlight-llms-txt`.
+ */
+export const starlightLlmsTxtPlugin = starlightLlmsTxt({
+  exclude: [
+    "docs/integrate/integration-options/enssdk/example",
+    "docs/integrate/integration-options/enskit/example",
+    "docs/integrate/omnigraph/schema-reference",
+  ],
+});

docs/ensnode.io/config/integrations/starlight/index.ts

@@ -1,13 +1,14 @@
 import AstroStarlight from "@astrojs/starlight";
 import type { AstroIntegration } from "astro";
-import starlightLlmsTxt from "starlight-llms-txt";
 import starlightSidebarTopics from "starlight-sidebar-topics";
 
+import { starlightLlmsTxtPlugin } from "../llms-txt";
 import { starlightSidebarTopicsConfig } from "./sidebar-topics";
 
 export function starlight(): AstroIntegration {
   return AstroStarlight({
     components: {
+      PageFrame: "./src/components/overrides/PageFrame.astro",
       ThemeProvider: "./src/components/overrides/ThemeProvider.astro",
       ThemeSelect: "./src/components/overrides/ThemeSelect.astro",
       SocialIcons: "./src/components/overrides/SocialIcons.astro",
@@ -29,7 +30,7 @@ export function starlight(): AstroIntegration {
       "@fontsource/inter/800.css",
       "@fontsource/inter/900.css",
     ],
-    plugins: [starlightLlmsTxt(), starlightSidebarTopics(starlightSidebarTopicsConfig)],
+    plugins: [starlightLlmsTxtPlugin, starlightSidebarTopics(starlightSidebarTopicsConfig)],
     title: "ENSNode",
     disable404Route: true,
     logo: {

docs/ensnode.io/config/integrations/starlight/sidebar-topics/integrate.ts

@@ -28,8 +28,62 @@ export const integrateSidebarTopic = {
           link: "/docs/integrate/omnigraph",
         },
         {
-          label: "Cookbook",
-          link: "/docs/integrate/omnigraph/cookbook",
+          label: "Examples",
+          collapsed: false,
+          items: [
+            {
+              label: "Overview",
+              link: "/docs/integrate/omnigraph/examples",
+            },
+            {
+              label: "Domain By Name",
+              link: "/docs/integrate/omnigraph/examples/domain-by-name",
+            },
+            {
+              label: "Find Domains",
+              link: "/docs/integrate/omnigraph/examples/find-domains",
+            },
+            {
+              label: "Domain Subdomains",
+              link: "/docs/integrate/omnigraph/examples/domain-subdomains",
+            },
+            {
+              label: "Domain Events",
+              link: "/docs/integrate/omnigraph/examples/domain-events",
+            },
+            {
+              label: "Account Domains",
+              link: "/docs/integrate/omnigraph/examples/domains-by-address",
+            },
+            {
+              label: "Account Events",
+              link: "/docs/integrate/omnigraph/examples/account-events",
+            },
+            {
+              label: "Registry Domains",
+              link: "/docs/integrate/omnigraph/examples/registry-domains",
+            },
+            {
+              label: "Permissions By Contract",
+              link: "/docs/integrate/omnigraph/examples/permissions-by-contract",
+            },
+            {
+              label: "Permissions By User",
+              link: "/docs/integrate/omnigraph/examples/permissions-by-user",
+            },
+            {
+              label: "Account Resolver Permissions",
+              link: "/docs/integrate/omnigraph/examples/account-resolver-permissions",
+            },
+            {
+              label: "Domain Resolver",
+              link: "/docs/integrate/omnigraph/examples/domain-resolver",
+            },
+            {
+              label: "Namegraph",
+              link: "/docs/integrate/omnigraph/examples/namegraph",
+            },
+          ],
         },
         {
           label: "Schema Reference",
@@ -47,11 +101,31 @@ export const integrateSidebarTopic = {
         },
         {
           label: "enskit (React)",
-          link: "/docs/integrate/integration-options/enskit",
+          collapsed: false,
+          items: [
+            {
+              label: "Overview",
+              link: "/docs/integrate/integration-options/enskit",
+            },
+            {
+              label: "⚡ Interactive example",
+              link: "/docs/integrate/integration-options/enskit/example",
+            },
+          ],
         },
         {
           label: "enssdk (TypeScript)",
-          link: "/docs/integrate/integration-options/enssdk",
+          collapsed: false,
+          items: [
+            {
+              label: "Overview",
+              link: "/docs/integrate/integration-options/enssdk",
+            },
+            {
+              label: "⚡ Interactive example",
+              link: "/docs/integrate/integration-options/enssdk/example",
+            },
+          ],
         },
         {
           label: "ENS Omnigraph (GraphQL)",

docs/ensnode.io/package.json

@@ -13,6 +13,8 @@
     "astro": "astro",
     "lint": "biome check --write",
     "lint:ci": "biome ci",
+    "omnigraph-examples:refresh-responses": "tsx --tsconfig tsconfig.json scripts/fetch-omnigraph-example-responses.mts",
+    "test": "vitest",
     "generate:openapi": "pnpm --filter ensapi exec tsx --tsconfig tsconfig.json ../../scripts/generate-ensapi-openapi.mts"
   },
   "dependencies": {
@@ -26,6 +28,12 @@
     "@iconify-json/lucide": "^1.2.52",
     "@namehash/namehash-ui": "workspace:*",
     "@octokit/rest": "^20.1.2",
+    "@ensnode/ensnode-sdk": "0.0.0-preview-fix-sha-89c022b-20260518142147",
+    "@graphiql/plugin-doc-explorer": "0.4.1",
+    "@graphiql/react": "0.37.1",
+    "enssdk": "0.0.0-preview-fix-sha-89c022b-20260518142147",
+    "graphql": "^16.10.0",
+    "@stackblitz/sdk": "^1.11.0",
     "@scalar/astro": "^0.2.16",
     "@tailwindcss/vite": "catalog:",
     "astro": "catalog:",
@@ -40,12 +48,15 @@
     "react-dom": "catalog:",
     "react-wrap-balancer": "^1.1.1",
     "sharp": "^0.33.5",
+    "yaml": "^2.8.3",
     "starlight-llms-txt": "^0.10.0",
     "starlight-sidebar-topics": "^0.7.1",
     "tailwindcss": "catalog:"
   },
   "devDependencies": {
     "@types/react": "catalog:",
-    "@types/react-dom": "catalog:"
+    "@types/react-dom": "catalog:",
+    "tsx": "^4.19.3",
+    "vitest": "catalog:"
   }
 }

docs/ensnode.io/scripts/fetch-omnigraph-example-responses.mts

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getNamespaceSpecificValue } from "@ensnode/ensnode-sdk";
+import { getGraphqlApiExampleQueryById } from "@ensnode/ensnode-sdk/internal";
+
+import { OMNIGRAPH_EXAMPLES_META } from "../src/data/omnigraph-examples/meta.ts";
+import { DOCS_OMNIGRAPH_NAMESPACE, ENSNODE_URL } from "../src/lib/playground/constants.ts";
+
+function logStep(message: string, id?: string) {
+  console.log(`[omnigraph-examples] ${message} ${id ? `for '${id}'` : ""}`);
+}
+
+function logError(message: string, id?: string) {
+  console.error(`[omnigraph-examples] ERROR: ${message} ${id ? `for example '${id}'` : ""}`);
+}
+
+const allExampleIds = (Object.keys(OMNIGRAPH_EXAMPLES_META) as string[]).sort();
+
+const outputPath = join(
+  dirname(fileURLToPath(import.meta.url)),
+  "../src/data/omnigraph-examples/responses.json",
+);
+
+// Optional filter: `pnpm omnigraph-examples:refresh-responses <id>,<id>`
+const argIds =
+  process.argv[2]
+    ?.split(",")
+    .map((s) => s.trim())
+    .filter(Boolean) ?? [];
+
+if (argIds.length > 0) {
+  const unknown = argIds.filter((id) => !allExampleIds.includes(id));
+  if (unknown.length > 0) {
+    logError(`Unknown example ID(s): ${unknown.join(", ")}. Known: ${allExampleIds.join(", ")}`);
+    process.exit(1);
+  }
+}
+
+const exampleIds = argIds.length > 0 ? argIds : allExampleIds;
+
+const base = ENSNODE_URL.replace(/\/+$/, "");
+const url = `${base}/api/omnigraph`;
+
+logStep(
+  argIds.length > 0
+    ? `Refreshing ${exampleIds.length} of ${allExampleIds.length} examples from ${url}: ${exampleIds.join(", ")}`
+    : `Fetching all ${exampleIds.length} Omnigraph examples from ${url}`,
+);
+
+// When refreshing a subset, load the existing responses so unaffected entries are preserved.
+const out: Record<string, unknown> =
+  argIds.length > 0 && existsSync(outputPath)
+    ? (JSON.parse(readFileSync(outputPath, "utf8")) as Record<string, unknown>)
+    : {};
+
+for (const id of exampleIds) {
+  logStep("Getting example query", id);
+
+  const example = getGraphqlApiExampleQueryById(id);
+  const query = example.query.trim();
+  const variables = getNamespaceSpecificValue(DOCS_OMNIGRAPH_NAMESPACE, example.variables);
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query, variables }),
+    signal: AbortSignal.timeout(120_000),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    logError(`HTTP ${response.status}. Body (first 800 chars):\n${text.slice(0, 800)}`, id);
+    process.exit(1);
+  }
+
+  const body = await response.json();
+
+  if (
+    typeof body === "object" &&
+    body !== null &&
+    "errors" in body &&
+    Array.isArray((body as { errors: unknown }).errors) &&
+    (body as { errors: unknown[] }).errors.length > 0
+  ) {
+    logError(`GraphQL errors: ${JSON.stringify(body, null, 2)}`, id);
+    process.exit(1);
+  }
+
+  out[id] = body;
+  logStep("Success", id);
+}
+
+logStep(`Writing responses to ${outputPath}`);
+writeFileSync(outputPath, `${JSON.stringify(out, null, 2)}\n`, "utf8");
+logStep("Done.");