polen 0.10.0 → 0.11.0-next.10

package/build/template/server/ssg/get-route-paths.js

@@ -1,7 +1,8 @@
-import { Grafaid } from '#lib/grafaid/index';
-import { visit } from 'graphql';
-// Or your specific import path for this type
+import { Api } from '#api/index';
 import { ReactRouterAid } from '#lib/react-router-aid/index';
+import { visit } from 'graphql';
+import * as NodeFs from 'node:fs/promises';
+import * as NodePath from 'node:path';
 import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper';
 import { routes } from '../../routes.js';
 // todo: Frameworks tend to colocate ssg data loaders with routes to solve the following
@@ -9,35 +10,97 @@ import { routes } from '../../routes.js';
 // Maybe we can figure something out too.
 const knownParameterizedRouteExpressions = {
     reference_type: `/reference/:type`,
+    reference_type_field: `/reference/:type/:field`,
+    reference_version: `/reference/version/:version`,
+    reference_versioned_type: `/reference/version/:version/:type`,
+    reference_versioned_type_field: `/reference/version/:version/:type/:field`,
 };
-export const getRoutesPaths = () => {
+export const getRoutesPaths = async () => {
     const paths = new Set();
     const routeExpressions = ReactRouterAid.getRouteExpressions(routes);
+    // Helper function to load schema from filesystem and add type paths
+    const addTypePathsForVersion = async (version, pathPrefix, includeFields = false) => {
+        try {
+            const schemaFilePath = NodePath.join(PROJECT_DATA.paths.project.absolute.build.assets.schemas, `${version}.json`);
+            const schemaContent = await NodeFs.readFile(schemaFilePath, 'utf-8');
+            const schemaAst = JSON.parse(schemaContent);
+            visit(schemaAst, {
+                ObjectTypeDefinition(node) {
+                    const typePath = `${pathPrefix}/${node.name.value}`;
+                    paths.add(typePath);
+                    // Add field paths if requested
+                    if (includeFields && node.fields) {
+                        for (const field of node.fields) {
+                            paths.add(`${typePath}/${field.name.value}`);
+                        }
+                    }
+                },
+                InterfaceTypeDefinition(node) {
+                    const typePath = `${pathPrefix}/${node.name.value}`;
+                    paths.add(typePath);
+                    // Add field paths if requested
+                    if (includeFields && node.fields) {
+                        for (const field of node.fields) {
+                            paths.add(`${typePath}/${field.name.value}`);
+                        }
+                    }
+                },
+                EnumTypeDefinition(node) {
+                    paths.add(`${pathPrefix}/${node.name.value}`);
+                },
+                InputObjectTypeDefinition(node) {
+                    paths.add(`${pathPrefix}/${node.name.value}`);
+                },
+                UnionTypeDefinition(node) {
+                    paths.add(`${pathPrefix}/${node.name.value}`);
+                },
+                ScalarTypeDefinition(node) {
+                    paths.add(`${pathPrefix}/${node.name.value}`);
+                },
+            });
+        }
+        catch (error) {
+            throw new Error(`SSG failed to load schema for version ${version}. Ensure schema assets are built. ${error}`);
+        }
+    };
+    const schemaMetadataPath = NodePath.join(PROJECT_DATA.paths.project.absolute.build.assets.schemas, 'metadata.json');
+    const schemaMetadata = await Api.Schema.getMetadata(schemaMetadataPath);
+    const { hasSchema, versions: availableVersions } = schemaMetadata;
     for (const exp of routeExpressions) {
         if (exp === knownParameterizedRouteExpressions.reference_type) {
-            if (PROJECT_DATA.schema) {
-                const schema = PROJECT_DATA.schema.versions[0].after;
-                const ast = Grafaid.Schema.AST.parse(Grafaid.Schema.print(schema));
-                visit(ast, {
-                    ObjectTypeDefinition(node) {
-                        paths.add(`/reference/${node.name.value}`);
-                    },
-                    InterfaceTypeDefinition(node) {
-                        paths.add(`/reference/${node.name.value}`);
-                    },
-                    EnumTypeDefinition(node) {
-                        paths.add(`/reference/${node.name.value}`);
-                    },
-                    InputObjectTypeDefinition(node) {
-                        paths.add(`/reference/${node.name.value}`);
-                    },
-                    UnionTypeDefinition(node) {
-                        paths.add(`/reference/${node.name.value}`);
-                    },
-                    ScalarTypeDefinition(node) {
-                        paths.add(`/reference/${node.name.value}`);
-                    },
-                });
+            if (hasSchema) {
+                // Add paths for latest version (no version in URL)
+                await addTypePathsForVersion(Api.Schema.VERSION_LATEST, `/reference`);
+            }
+        }
+        else if (exp === knownParameterizedRouteExpressions.reference_version) {
+            if (hasSchema) {
+                // Add paths for version pages themselves (without type)
+                for (const version of availableVersions) {
+                    paths.add(`/reference/version/${version}`);
+                }
+            }
+        }
+        else if (exp === knownParameterizedRouteExpressions.reference_type_field) {
+            if (hasSchema) {
+                // Add paths for latest version fields
+                await addTypePathsForVersion(Api.Schema.VERSION_LATEST, `/reference`, true);
+            }
+        }
+        else if (exp === knownParameterizedRouteExpressions.reference_versioned_type) {
+            if (hasSchema) {
+                // Add paths for all versions using new route structure
+                for (const version of availableVersions) {
+                    await addTypePathsForVersion(version, `/reference/version/${version}`);
+                }
+            }
+        }
+        else if (exp === knownParameterizedRouteExpressions.reference_versioned_type_field) {
+            if (hasSchema) {
+                // Add paths for all versions with fields
+                for (const version of availableVersions) {
+                    await addTypePathsForVersion(version, `/reference/version/${version}`, true);
+                }
             }
         }
         else if (ReactRouterAid.isParameterizedPath(exp)) {

package/build/template/server/ssg/get-route-paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-route-paths.js","sourceRoot":"","sources":["../../../../src/template/server/ssg/get-route-paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAC/B,6CAA6C;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AAC5D,OAAO,YAAY,MAAM,sCAAsC,CAAA;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAExC,wFAAwF;AACxF,uEAAuE;AACvE,yCAAyC;AACzC,MAAM,kCAAkC,GAAG;IACzC,cAAc,EAAE,kBAAkB;CACnC,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,GAAa,EAAE;IAC3C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAA;IAC/B,MAAM,gBAAgB,GAAG,cAAc,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAA;IAEnE,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,IAAI,GAAG,KAAK,kCAAkC,CAAC,cAAc,EAAE,CAAC;YAC9D,IAAI,YAAY,CAAC,MAAM,EAAE,CAAC;gBACxB,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;gBACpD,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAA;gBAClE,KAAK,CAAC,GAAG,EAAE;oBACT,oBAAoB,CAAC,IAAI;wBACvB,KAAK,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;oBAC5C,CAAC;oBACD,uBAAuB,CAAC,IAAI;wBAC1B,KAAK,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;oBAC5C,CAAC;oBACD,kBAAkB,CAAC,IAAI;wBACrB,KAAK,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;oBAC5C,CAAC;oBACD,yBAAyB,CAAC,IAAI;wBAC5B,KAAK,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;oBAC5C,CAAC;oBACD,mBAAmB,CAAC,IAAI;wBACtB,KAAK,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;oBAC5C,CAAC;oBACD,oBAAoB,CAAC,IAAI;wBACvB,KAAK,CAAC,GAAG,CAAC,cAAc,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;oBAC5C,CAAC;iBACF,CAAC,CAAA;YACJ,CAAC;QACH,CAAC;aAAM,IAAI,cAAc,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,iCAAiC,GAAG,EAAE,CAAC,CAAA;QACzD,CAAC;aAAM,CAAC;YACN,cAAc;YACd,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAChB,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA,CAAC,gCAAgC;AAClE,CAAC,CAAA"}
+{"version":3,"file":"get-route-paths.js","sourceRoot":"","sources":["../../../../src/template/server/ssg/get-route-paths.ts"],"names":[],"mappings":"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"}

package/build/template/sources/schema-source.d.ts

@@ -0,0 +1,15 @@
+export declare const schemaSource: {
+    versions: string[];
+    isEmpty: boolean;
+    get: (version: string) => Promise<import("graphql").GraphQLSchema>;
+    getChangelog: (version: string) => Promise<import("../../api/schema/schema.js").ChangelogData>;
+    getAllChangesets: () => Promise<import("../../lib/graphql-changeset/graphql-changeset.js").ChangeSet[]>;
+    clearCache: () => void;
+    writeSchema: (version: string, schema: import("graphql").GraphQLSchema) => Promise<void>;
+    writeChangelog: (version: string, changelog: import("../../api/schema/schema.js").ChangelogData) => Promise<void>;
+    clearAllAssets: () => Promise<void>;
+    removeAsset: (version: string) => Promise<void>;
+    writeMetadata: (metadata: import("../../api/schema/metadata.js").SchemaMetadata) => Promise<void>;
+    writeAllAssets: (schemaData: Awaited<ReturnType<typeof import("../../api/schema/read.js").readOrThrow>>["data"], metadata: import("../../api/schema/metadata.js").SchemaMetadata) => Promise<void>;
+};
+//# sourceMappingURL=schema-source.d.ts.map

package/build/template/sources/schema-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-source.d.ts","sourceRoot":"","sources":["../../../src/template/sources/schema-source.ts"],"names":[],"mappings":"AAkDA,eAAO,MAAM,YAAY;;;;;;;;;;;;;CAIvB,CAAA"}

package/build/template/sources/schema-source.js

@@ -0,0 +1,64 @@
+import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper';
+import PROJECT_SCHEMA_METADATA from 'virtual:polen/project/schema-metadata';
+import { createSchemaSource } from '../../api/schema-source/index.js';
+import { polenUrlPathAssets } from '../lib/polen-url.js';
+// Environment-specific IO implementation
+const io = import.meta.env.SSR
+    ? {
+        // Server-side: Read from filesystem
+        read: async (path) => {
+            // Dynamic import to keep fs out of client bundle
+            const { readFile } = await import('node:fs/promises');
+            // Extract the path after the assets route
+            // e.g., "/assets/schemas/latest.json" -> "schemas/latest.json"
+            // e.g., "/demos/pokemon/assets/schemas/latest.json" -> "schemas/latest.json"
+            const assetsRoute = PROJECT_DATA.server.routes.assets;
+            const routePattern = new RegExp(`${assetsRoute}/(.+)$`);
+            const match = path.match(routePattern);
+            const assetPath = match ? match[1] : path;
+            // In SSR, we need to read from the correct location
+            // During dev, assets are served from Polen's node_modules
+            // In production, they're in the build output directory
+            let fullPath;
+            if (import.meta.env.DEV) {
+                // Development: Read from Polen's Vite cache
+                fullPath = `${PROJECT_DATA.paths.framework.devAssets.absolute}/${assetPath}`;
+            }
+            else {
+                // Production: Read from build output
+                // The server runs from the project root, and assets are in build/assets/
+                fullPath =
+                    `${PROJECT_DATA.paths.project.relative.build.root}/${PROJECT_DATA.paths.project.relative.build.relative.assets.root}/${assetPath}`;
+            }
+            return readFile(fullPath, 'utf-8');
+        },
+    }
+    : {
+        // Client-side: Fetch from HTTP
+        read: async (path) => {
+            const response = await fetch(path);
+            if (!response.ok) {
+                throw new Error(`Failed to fetch: ${path} (${response.status} ${response.statusText})`);
+            }
+            return response.text();
+        },
+    };
+// Create and export the source object directly
+export const schemaSource = createSchemaSource({
+    io,
+    versions: PROJECT_SCHEMA_METADATA.versions,
+    assetsPath: polenUrlPathAssets(),
+});
+// HMR cache invalidation for development
+if (import.meta.hot) {
+    import.meta.hot.on('polen:schema-invalidate', () => {
+        console.log('[HMR] Schema cache invalidated');
+        schemaSource.clearCache();
+        // Brute force approach: reload the page to ensure fresh data
+        // This guarantees all components see the updated schema immediately
+        // TODO: When we have reactive data fetching, remove this reload
+        //       and let the reactive system handle updates gracefully
+        window.location.reload();
+    });
+}
+//# sourceMappingURL=schema-source.js.map

package/build/template/sources/schema-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-source.js","sourceRoot":"","sources":["../../../src/template/sources/schema-source.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,sCAAsC,CAAA;AAC/D,OAAO,uBAAuB,MAAM,uCAAuC,CAAA;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAA;AACrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAExD,yCAAyC;AACzC,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG;IAC5B,CAAC,CAAC;QACA,oCAAoC;QACpC,IAAI,EAAE,KAAK,EAAE,IAAY,EAAE,EAAE;YAC3B,iDAAiD;YACjD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,kBAAkB,CAAC,CAAA;YAErD,0CAA0C;YAC1C,+DAA+D;YAC/D,6EAA6E;YAC7E,MAAM,WAAW,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAA;YACrD,MAAM,YAAY,GAAG,IAAI,MAAM,CAAC,GAAG,WAAW,QAAQ,CAAC,CAAA;YACvD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;YACtC,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;YAEzC,oDAAoD;YACpD,0DAA0D;YAC1D,uDAAuD;YACvD,IAAI,QAAgB,CAAA;YACpB,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;gBACxB,4CAA4C;gBAC5C,QAAQ,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,QAAQ,IAAI,SAAS,EAAE,CAAA;YAC9E,CAAC;iBAAM,CAAC;gBACN,qCAAqC;gBACrC,yEAAyE;gBACzE,QAAQ;oBACN,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,IAAI,YAAY,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,SAAS,EAAE,CAAA;YACtI,CAAC;YAED,OAAO,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QACpC,CAAC;KACF;IACD,CAAC,CAAC;QACA,+BAA+B;QAC/B,IAAI,EAAE,KAAK,EAAE,IAAY,EAAE,EAAE;YAC3B,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAA;YAClC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,KAAK,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,GAAG,CAAC,CAAA;YACzF,CAAC;YACD,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAA;QACxB,CAAC;KACF,CAAA;AAEH,+CAA+C;AAC/C,MAAM,CAAC,MAAM,YAAY,GAAG,kBAAkB,CAAC;IAC7C,EAAE;IACF,QAAQ,EAAE,uBAAuB,CAAC,QAAQ;IAC1C,UAAU,EAAE,kBAAkB,EAAE;CACjC,CAAC,CAAA;AAEF,yCAAyC;AACzC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;IACpB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACjD,OAAO,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAA;QAC7C,YAAY,CAAC,UAAU,EAAE,CAAA;QAEzB,6DAA6D;QAC7D,oEAAoE;QACpE,gEAAgE;QAChE,8DAA8D;QAC9D,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAA;IAC1B,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polen",
-  "version": "0.10.0",
+  "version": "0.11.0-next.10",
   "type": "module",
   "description": "A framework for delightful GraphQL developer portals",
   "author": {
@@ -87,18 +87,18 @@
     "@graphql-inspector/core": "^6.2.1",
     "@graphql-tools/load": "^8.1.0",
     "@hiogawa/vite-plugin-ssr-css": "^0.0.1",
-    "@hono/node-server": "^1.15.0",
+    "@hono/node-server": "^1.16.0",
     "@mdx-js/mdx": "^3.1.0",
     "@mdx-js/react": "^3.1.0",
     "@mdx-js/rollup": "^3.1.0",
     "@radix-ui/react-icons": "^1.3.2",
     "@radix-ui/themes": "^3.2.1",
-    "@rolldown/pluginutils": "1.0.0-beta.24",
+    "@rolldown/pluginutils": "1.0.0-beta.27",
     "@rollup/pluginutils": "^5.2.0",
     "@types/jsesc": "^3.0.3",
     "@vitejs/plugin-react": "^4.6.0",
     "@vitejs/plugin-react-oxc": "^0.2.3",
-    "@vltpkg/semver": "0.0.0-16",
+    "@vltpkg/semver": "0.0.0-17",
     "@vue/reactivity": "^3.5.17",
     "@wollybeard/kit": "^0.41.0",
     "@wollybeard/projector": "^0.3.0",
@@ -107,12 +107,12 @@
     "codehike": "^1.0.7",
     "consola": "^3.4.2",
     "defu": "^6.1.4",
-    "es-toolkit": "^1.39.6",
+    "es-toolkit": "^1.39.7",
     "fuse.js": "^7.1.0",
     "graffle": "8.0.0-next.163",
     "graphql": "^16.11.0",
     "gray-matter": "^4.0.3",
-    "hono": "^4.8.4",
+    "hono": "^4.8.5",
     "jsesc": "^3.1.0",
     "jsonc-parser": "^3.3.1",
     "react": "^19.1.0",
@@ -126,22 +126,21 @@
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "resolve.imports": "^2.0.3",
-    "rolldown": "1.0.0-beta.24",
+    "rolldown": "1.0.0-beta.27",
     "simple-git": "^3.28.0",
     "source-map": "^0.7.4",
     "superjson": "^2.2.2",
     "tinyglobby": "^0.2.14",
-    "tree-sitter-graphql-grammar-wasm": "^1.0.0",
+    "tree-sitter-graphql-grammar-wasm": "^1.1.0",
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
     "unified": "^11.0.5",
     "vfile": "^6.0.3",
-    "vite": "npm:rolldown-vite@^7.0.4",
+    "vite": "npm:rolldown-vite@^7.0.9",
     "vite-plugin-inspect": "^11.3.0",
-    "vite-plugin-restart": "^0.4.2",
-    "web-tree-sitter": "^0.25.6",
+    "web-tree-sitter": "^0.25.8",
     "youch-core": "^0.3.3",
-    "zx": "8.6.1"
+    "zx": "8.7.1"
   },
   "devDependencies": {
     "@actions/core": "^1.11.1",
@@ -151,15 +150,15 @@
     "@actions/io": "^1.1.3",
     "@changesets/cli": "^2.29.5",
     "@molt/command": "^0.9.0",
-    "@octokit/core": "^7.0.2",
+    "@octokit/core": "^7.0.3",
     "@octokit/types": "^14.1.0",
-    "@playwright/browser-chromium": "^1.53.2",
+    "@playwright/browser-chromium": "^1.54.1",
     "@testing-library/react": "^16.3.0",
     "@tsconfig/node-lts": "^22.0.2",
     "@tsconfig/node22": "^22.0.2",
     "@tsconfig/strictest": "^2.0.5",
     "@types/jsdom": "^21.1.7",
-    "@types/node": "^24.0.10",
+    "@types/node": "^24.0.14",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@types/semver": "^7.7.0",
@@ -167,10 +166,10 @@
     "dripip": "^0.10.0",
     "fast-check": "^4.2.0",
     "fs-jetpack": "^5.1.0",
-    "get-port-please": "^3.1.2",
+    "get-port-please": "^3.2.0",
     "globals": "^16.3.0",
     "jsdom": "^26.1.0",
-    "playwright": "1.53.2",
+    "playwright": "1.54.1",
     "publint": "^0.3.12",
     "semver": "^7.7.2",
     "strip-ansi": "^7.1.0",

package/src/api/api.ts

@@ -2,4 +2,5 @@ export * from './builder/index.js'
 export * from './config-resolver/index.js'
 export * from './config/index.js'
 export * as Project from './project/index.js'
+export * from './schema/index.js'
 export * from './static/index.js'

package/src/api/config/configurator.ts

@@ -31,25 +31,56 @@ export interface ConfigInput {
    * - `file` - Load from a single SDL file (default: schema.graphql)
    * - `directory` - Load multiple SDL files with date prefixes (enables changelog)
    * - `memory` - Define schemas programmatically in configuration
+   * - `introspection` - Fetch schema from a GraphQL endpoint
+   * - `data` - Use pre-built schema objects
    *
    * @example
    * ```ts
-   * // Single file
+   * // Default: looks for schema.graphql
+   * schema: {}
+   *
+   * // Load via introspection
    * schema: {
-   *   useDataSources: 'file',
    *   dataSources: {
-   *     file: { path: './my-schema.graphql' }
+   *     introspection: {
+   *       url: 'https://api.example.com/graphql',
+   *       headers: { 'Authorization': `Bearer ${process.env.API_TOKEN}` }
+   *     }
    *   }
    * }
    *
    * // Multiple versions for changelog
    * schema: {
-   *   useDataSources: 'directory',
    *   dataSources: {
    *     directory: { path: './schema' }
    *   }
    * }
+   *
+   * // Custom source order
+   * schema: {
+   *   useDataSources: ['introspection', 'file'],
+   *   dataSources: {
+   *     introspection: { url: 'https://api.example.com/graphql' },
+   *     file: { path: './fallback.graphql' }
+   *   }
+   * }
    * ```
+   *
+   * **Two introspection features**:
+   * 1. **File Convention**: Polen auto-detects `schema.introspection.json` files
+   * 2. **Config-driven**: Polen fetches and caches introspection for you
+   *
+   * **Interoperability**: The `schema.introspection.json` file uses the standard
+   * GraphQL introspection format, compatible with GraphQL Codegen, Apollo CLI, etc.
+   *
+   * **Lifecycle**:
+   * - First run: Fetches from endpoint, saves to `schema.introspection.json`
+   * - Subsequent runs: Loads from JSON file (no network request)
+   * - To refresh: Delete the JSON file
+   * - Runs during `polen dev` and `polen build`, never at runtime
+   *
+   * **Query details**: Uses the standard introspection query from the GraphQL spec
+   * @see https://spec.graphql.org/draft/#sec-Introspection
    */
   schema?: SchemaConfigInput
   /**
@@ -240,22 +271,6 @@ export interface ConfigInput {
      * @default false
      */
     isSelfContainedMode?: boolean
-    /**
-     * Tweak the watch behavior.
-     */
-    watch?: {
-      /**
-       * Restart the development server when some arbitrary files change.
-       *
-       * Use this to restart when files that are not already watched by vite change.
-       *
-       * @see https://github.com/antfu/vite-plugin-restart
-       */
-      /**
-       * File paths to watch and restart the development server when they change.
-       */
-      also?: string[]
-    }
     /**
      * Whether to enable debug mode.
      *
@@ -289,6 +304,13 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
 
   const publicAbsolutePath = rootAbsolute(`public`)
   const publicAbsolute = Path.ensureAbsoluteWith(publicAbsolutePath)
+
+  const assetsAbsolute = Path.ensureAbsoluteWith(buildAbsolute(`assets`))
+
+  // Dev assets paths
+  const devAssetsRelative = 'node_modules/.vite/polen-assets'
+  const devAssetsAbsolute = Path.join(packagePaths.rootDir, devAssetsRelative)
+
   return {
     project: {
       rootDir,
@@ -297,7 +319,12 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
           root: `build`,
           relative: {
             serverEntrypoint: `app.js`,
-            assets: `assets`,
+            assets: {
+              root: `assets`,
+              relative: {
+                schemas: `schemas`,
+              },
+            },
           },
         },
         pages: `pages`,
@@ -311,7 +338,10 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
         build: {
           root: buildAbsolute(`.`),
           serverEntrypoint: buildAbsolute(`app.js`),
-          assets: buildAbsolute(`assets`),
+          assets: {
+            root: buildAbsolute(`assets`),
+            schemas: assetsAbsolute(`schemas`),
+          },
         },
         public: {
           root: publicAbsolute(`.`),
@@ -319,7 +349,14 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
         },
       },
     },
-    framework: packagePaths,
+    framework: {
+      ...packagePaths,
+      devAssets: {
+        relative: devAssetsRelative,
+        absolute: devAssetsAbsolute,
+        schemas: Path.join(devAssetsAbsolute, 'schemas'),
+      },
+    },
   }
 }
 
@@ -331,9 +368,9 @@ export interface Config {
   }
   server: {
     port: number
-  }
-  watch: {
-    also: string[]
+    routes: {
+      assets: string
+    }
   }
   templateVariables: TemplateVariables
   schemaAugmentations: SchemaAugmentation.Augmentation[]
@@ -353,7 +390,12 @@ export interface Config {
         build: {
           root: string
           relative: {
-            assets: string
+            assets: {
+              root: string
+              relative: {
+                schemas: string
+              }
+            }
             serverEntrypoint: string
           }
         }
@@ -366,7 +408,10 @@ export interface Config {
       absolute: {
         build: {
           root: string
-          assets: string
+          assets: {
+            root: string
+            schemas: string
+          }
           serverEntrypoint: string
         }
         pages: string
@@ -376,7 +421,13 @@ export interface Config {
         }
       }
     }
-    framework: PackagePaths
+    framework: PackagePaths & {
+      devAssets: {
+        relative: string
+        absolute: string
+        schemas: string
+      }
+    }
   }
   advanced: {
     isSelfContainedMode: boolean
@@ -392,15 +443,15 @@ const configInputDefaults: Config = {
     title: `My Developer Portal`,
   },
   schemaAugmentations: [],
-  watch: {
-    also: [],
-  },
   build: {
     architecture: BuildArchitecture.enum.ssg,
     base: `/`,
   },
   server: {
     port: 3000,
+    routes: {
+      assets: '/assets',
+    },
   },
   schema: null,
   ssr: {
@@ -499,14 +550,13 @@ export const normalizeInput = async (
     config.advanced.explorer = configInput.advanced.explorer
   }
 
-  if (configInput?.advanced?.watch?.also) {
-    config.watch.also = configInput.advanced.watch.also
-  }
-
   if (configInput?.server?.port !== undefined) {
     config.server.port = configInput.server.port
   }
 
+  // Server routes are not configurable by users yet, use defaults
+  // config.server.routes is already set from defaultConfig
+
   // Process warnings configuration
   if (configInput?.warnings?.interactiveWithoutSchema?.enabled !== undefined) {
     config.warnings.interactiveWithoutSchema.enabled = configInput.warnings.interactiveWithoutSchema.enabled

package/src/api/config/merge.ts

@@ -48,22 +48,6 @@ export const mergeInputs = (
   if (base.advanced ?? overrides.advanced) {
     merged.advanced = spreadShallow(base.advanced, overrides.advanced)
 
-    // Merge advanced.watch config
-    if (base.advanced?.watch ?? overrides.advanced?.watch) {
-      merged.advanced.watch = spreadShallow(
-        base.advanced?.watch,
-        overrides.advanced?.watch,
-      )
-
-      // Merge watch.also arrays
-      if (base.advanced?.watch?.also ?? overrides.advanced?.watch?.also) {
-        merged.advanced.watch.also = [
-          ...(base.advanced?.watch?.also ?? []),
-          ...(overrides.advanced?.watch?.also ?? []),
-        ]
-      }
-    }
-
     // Merge Vite configs if present
     if (base.advanced?.vite ?? overrides.advanced?.vite) {
       merged.advanced.vite = Vite.mergeConfig(

package/src/api/content/metadata.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod/v4'
+import { z } from 'zod'
 
 /**
  * Schema for validating front matter content

package/src/api/schema/data-sources/data-sources.ts

@@ -1,3 +1,4 @@
+export * as Introspection from './introspection/introspection.js'
 export * as Memory from './memory/memory.js'
 export * as SchemaDirectory from './schema-directory/schema-directory.js'
 export * as SchemaFile from './schema-file/schema-file.js'