veryfront 0.1.1102 → 0.1.1104

package/esm/src/rendering/orchestrator/module-loader/index.js

@@ -16,6 +16,8 @@ import { resolveModuleDependencies, rewriteResolvedDependencyImports, } from "./
 import { persistTransformedModule } from "./module-persistence.js";
 import { transformModuleCodeWithCache } from "./module-transform-cache.js";
 import { getModuleCacheKey, resolveCachedModulePath } from "./module-cache-lookup.js";
+import { markBuildFailure } from "./build-failure.js";
+export { isBuildFailure } from "./build-failure.js";
 const logger = rendererLogger.component("module-loader");
 // Re-export utilities
 export { createEsmCache, createModuleCache, generateHash } from "./cache.js";
@@ -35,7 +37,12 @@ function decodeFileContent(fileContent) {
  * @param useLocalAdapter - Whether to use local adapter for reading
  * @returns Path to the transformed module file
  */
-export async function transformModuleWithDeps(filePath, tmpDir, localAdapter, config, useLocalAdapter = false) {
+export async function transformModuleWithDeps(filePath, tmpDir, localAdapter, config, useLocalAdapter = false, lineage = new Set(), 
+// Shared by reference across the whole transform tree (unlike `lineage`, which
+// is copied per level): a descendant records a cycle target here, and the
+// ancestor that eventually persists that target reads it to write a stable
+// alias the left-as-authored cycle edge can resolve to.
+cycleTargets = new Set()) {
     const { moduleCache, projectDir, projectId, contentSourceId, adapter, mode } = config;
     const cacheKey = getModuleCacheKey(filePath, projectId, projectDir, contentSourceId, config.reactVersion, mode);
     const cachedPath = await resolveCachedModulePath({
@@ -58,15 +65,55 @@ export async function transformModuleWithDeps(filePath, tmpDir, localAdapter, co
         filePath,
         projectDir,
     });
-    const transformedDeps = await Promise.all(resolvedDeps.filter((d) => d.depFilePath).map(async (dep) => {
+    // The module cache is only written once a transform completes, so it cannot
+    // break a cycle that is still in progress. Carry the chain instead.
+    const nextLineage = new Set(lineage).add(filePath);
+    const transformedDeps = (await Promise.all(resolvedDeps.filter((d) => d.depFilePath).map(async (dep) => {
+        // `await import()` is how a module graph legitimately breaks an import
+        // cycle, so following one eagerly can lead straight back to a module
+        // further up this chain and recurse until the worker dies. Leave the
+        // specifier as authored so the recursion terminates.
+        //
+        // The cycle target is persisted as a content-hashed artifact whose hash
+        // is derived from transformed output we do not produce here (producing it
+        // is the recursion we are breaking), so the edge cannot be rewritten to
+        // that hashed path. Instead we record the target: when its ancestor
+        // persists it, a stable non-hashed alias is written next to the hashed
+        // artifact so the relative `.js` specifier esbuild leaves behind resolves.
+        // NOTE: this alias path is not yet runtime-verified end to end; if it does
+        // not resolve in a real runtime the cycle branch stays broken, which is no
+        // worse than before (and still a strict improvement over hanging).
+        if (nextLineage.has(dep.depFilePath)) {
+            cycleTargets.add(dep.depFilePath);
+            logger.debug("Skipping dependency already in the transform chain:", {
+                path: dep.path,
+                depFilePath: dep.depFilePath,
+            });
+            return null;
+        }
         logger.debug("Found dependency:", {
             path: dep.path,
             depFilePath: dep.depFilePath,
             isLocalLib: dep.isLocalLib,
         });
-        const depTempPath = await transformModuleWithDeps(dep.depFilePath, tmpDir, localAdapter, config, dep.isLocalLib);
-        return { ...dep, depTempPath };
-    }));
+        try {
+            const depTempPath = await transformModuleWithDeps(dep.depFilePath, tmpDir, localAdapter, config, dep.isLocalLib, nextLineage, cycleTargets);
+            return { ...dep, depTempPath };
+        }
+        catch (error) {
+            // A static import has to resolve for the importer to run at all. A
+            // dynamic one may never be evaluated, so a module behind an untaken
+            // branch must not fail the page that merely mentions it.
+            if (!dep.isDynamic)
+                throw error;
+            logger.warn("Leaving an unresolvable dynamic dependency as authored:", {
+                path: dep.path,
+                depFilePath: dep.depFilePath,
+                reason: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }))).filter((dep) => dep !== null);
     fileContent = rewriteResolvedDependencyImports(fileContent, transformedDeps);
     for (const dep of transformedDeps) {
         logger.debug("Replaced import:", {
@@ -103,6 +150,7 @@ export async function transformModuleWithDeps(filePath, tmpDir, localAdapter, co
         cacheKey,
         contentSourceId,
         reactVersion: config.reactVersion,
+        isCycleTarget: cycleTargets.has(filePath),
     });
 }
 /**
@@ -146,7 +194,15 @@ export function isMissingModuleError(error) {
 export async function loadModule(filePath, config) {
     const tmpDir = await getModuleCacheDir(config);
     const localAdapter = await getLocalAdapter();
-    const tempFilePath = await transformModuleWithDeps(filePath, tmpDir, localAdapter, config);
+    // Everything up to here compiles and resolves source, so a failure is a build
+    // failure. Everything after it is the module running.
+    let tempFilePath;
+    try {
+        tempFilePath = await transformModuleWithDeps(filePath, tmpDir, localAdapter, config);
+    }
+    catch (error) {
+        throw markBuildFailure(error);
+    }
     const moduleUrl = `file://${tempFilePath}`;
     try {
         return await import(moduleUrl);
@@ -189,7 +245,13 @@ export async function loadModule(filePath, config) {
             // invalidation stays scoped to this tenant (the path-cache key is not
             // project-scoped — see invalidateMdxEsmModule).
             invalidateMdxEsmModule(tmpDir, filePath, config.projectDir, config.reactVersion);
-            const rebuiltPath = await transformModuleWithDeps(filePath, tmpDir, localAdapter, config);
+            let rebuiltPath;
+            try {
+                rebuiltPath = await transformModuleWithDeps(filePath, tmpDir, localAdapter, config);
+            }
+            catch (rebuildError) {
+                throw markBuildFailure(rebuildError);
+            }
             return await import(`file://${rebuiltPath}?t=${Date.now()}&rebuilt=1`);
         }
         logger.error("Failed to import module:", {

package/esm/src/rendering/orchestrator/module-loader/module-persistence.d.ts

@@ -14,6 +14,12 @@ export interface PersistTransformedModuleInput {
     cacheKey: string;
     contentSourceId?: string;
     reactVersion?: string;
+    /**
+     * True when a dynamic import elsewhere closes a cycle back onto this module.
+     * Such an edge is left as authored (`import("../app/page.js")`), so it needs a
+     * stable, non-hashed alias next to the content-hashed artifact to resolve to.
+     */
+    isCycleTarget?: boolean;
 }
 /** Write a transformed module artifact and register cache pointers. */
 export declare function persistTransformedModule(input: PersistTransformedModuleInput): Promise<string>;

package/esm/src/rendering/orchestrator/module-loader/module-persistence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-persistence.d.ts","sourceRoot":"","sources":["../../../../../src/src/rendering/orchestrator/module-loader/module-persistence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAuDzE,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,cAAc,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,uEAAuE;AACvE,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,6BAA6B,GACnC,OAAO,CAAC,MAAM,CAAC,CA+DjB"}
+{"version":3,"file":"module-persistence.d.ts","sourceRoot":"","sources":["../../../../../src/src/rendering/orchestrator/module-loader/module-persistence.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAuDzE,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,cAAc,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAqDD,uEAAuE;AACvE,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,6BAA6B,GACnC,OAAO,CAAC,MAAM,CAAC,CAqEjB"}

package/esm/src/rendering/orchestrator/module-loader/module-persistence.js

@@ -44,6 +44,51 @@ async function ensureDir(adapter, dir, force = false) {
     createdDirs.add(dir);
     pruneCreatedDirs();
 }
+/**
+ * Whether transformed output exposes a default export, so a cycle alias knows
+ * to re-export it. Covers esbuild's `export default …`, `… as default`, and
+ * `export { default } from …` forms.
+ */
+function hasDefaultExport(code) {
+    return /\bexport\s+default\b/.test(code) ||
+        /\bas\s+default\b/.test(code) ||
+        /\bexport\s*\{[^}]*\bdefault\b[^}]*\}/.test(code);
+}
+/**
+ * Write a stable, non-hashed alias next to a cycle target's hashed artifact.
+ *
+ * A dynamic import that closes an import cycle is left as the author wrote it
+ * (see the module loader), so esbuild normalises it to a relative `.js` path
+ * (`../app/page.js`) that does not match the content-hashed artifact
+ * (`../app/page.<hash>.js`). The alias sits at that relative path and re-exports
+ * the real artifact, so the edge resolves if the branch runs. Best-effort: a
+ * failed alias just leaves the pre-existing (unresolved) cycle edge in place.
+ */
+async function writeCycleTargetAlias(input, relativePath, hashedFileName) {
+    const aliasRelativePath = relativePath.replace(/\.(tsx?|jsx|mdx)$/, ".js");
+    // Same extension in and out means nothing was renamed (already `.js`): the
+    // authored edge already points at the real artifact, so no alias is needed.
+    if (aliasRelativePath === relativePath)
+        return;
+    const aliasPath = join(input.tmpDir, aliasRelativePath);
+    const lines = [`export * from "./${hashedFileName}";`];
+    if (hasDefaultExport(input.transformedCode)) {
+        lines.push(`export { default } from "./${hashedFileName}";`);
+    }
+    try {
+        await input.localAdapter.fs.writeFile(aliasPath, lines.join("\n"));
+        logger.debug("Wrote cycle-target alias", {
+            alias: aliasRelativePath,
+            target: hashedFileName,
+        });
+    }
+    catch (error) {
+        logger.warn("Failed to write cycle-target alias", {
+            filePath: input.filePath.slice(-40),
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
 /** Write a transformed module artifact and register cache pointers. */
 export async function persistTransformedModule(input) {
     const transformedHash = hashCodeHex(input.transformedCode).slice(0, 8);
@@ -100,5 +145,9 @@ export async function persistTransformedModule(input) {
         });
     }
     input.moduleCache.set(input.cacheKey, tempFilePath);
+    if (input.isCycleTarget) {
+        const hashedFileName = jsPath.slice(jsPath.lastIndexOf("/") + 1);
+        await writeCycleTargetAlias(input, relativePath, hashedFileName);
+    }
     return tempFilePath;
 }

package/esm/src/rendering/orchestrator/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../../src/src/rendering/orchestrator/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,iCAAiC,CAAC;AASzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAqDhF,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACxE,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrF;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,YAAY,CAAC;IAC3B,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,YAAY,EAAE,YAAY,CAAC;IAC3B,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,eAAe,EAAE,eAAe,CAAC;IACjC,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,aAAa,GAAG,YAAY,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,OAAO,qBAAqB,EAAE,sBAAsB,CAAC;CAC1E;AA0BD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,mBAAmB,CAAgC;gBAE/C,MAAM,EAAE,oBAAoB;IAcxC,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,oBAAoB;IA0B5B;;;;OAIG;YACW,yBAAyB;IAWvC;;;OAGG;IACH,gBAAgB,IAAI,IAAI;IAKxB,OAAO,CAAC,UAAU;YAOJ,0BAA0B;IAaxC;;;;;;;;;OASG;YACW,qBAAqB;IA6DnC;;;OAGG;YACW,mBAAmB;IA6GjC,OAAO,CAAC,uBAAuB;IAkCzB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAyT9E,+EAA+E;IACzE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAsHzE,kBAAkB;YA2ClB,cAAc;IAW5B,OAAO,CAAC,uBAAuB;YAYjB,kBAAkB;IAyFhC,OAAO,CAAC,kBAAkB;YAQZ,uBAAuB;IAmBrC;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;CAStB"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../../src/src/rendering/orchestrator/pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,iCAAiC,CAAC;AASzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsDhF,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAE1D;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACxE,aAAa,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrF;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,EAAE,YAAY,CAAC;IAC3B,gBAAgB,EAAE,wBAAwB,CAAC;IAC3C,YAAY,EAAE,YAAY,CAAC;IAC3B,kBAAkB,EAAE,kBAAkB,CAAC;IACvC,eAAe,EAAE,eAAe,CAAC;IACjC,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,aAAa,GAAG,YAAY,CAAC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,OAAO,qBAAqB,EAAE,sBAAsB,CAAC;CAC1E;AA0BD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,mBAAmB,CAAgC;gBAE/C,MAAM,EAAE,oBAAoB;IAcxC,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,oBAAoB;IA0B5B;;;;OAIG;YACW,yBAAyB;IAWvC;;;OAGG;IACH,gBAAgB,IAAI,IAAI;IAKxB,OAAO,CAAC,UAAU;YAOJ,0BAA0B;IAaxC;;;;;;;;;OASG;YACW,qBAAqB;IAqEnC;;;OAGG;YACW,mBAAmB;IA6GjC,OAAO,CAAC,uBAAuB;IAkCzB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAyT9E,+EAA+E;IACzE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC;YAsHzE,kBAAkB;YA2ClB,cAAc;IAW5B,OAAO,CAAC,uBAAuB;YAYjB,kBAAkB;IAyFhC,OAAO,CAAC,kBAAkB;YAQZ,uBAAuB;IAmBrC;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;CAStB"}

package/esm/src/rendering/orchestrator/pipeline.js

@@ -35,6 +35,7 @@ import { buildReleaseAssetModules } from "../../release-assets/client-module-map
 import { getCSSByHashAsync, regenerateCSSByHash, } from "../../html/styles-builder/tailwind-compiler.js";
 import { getReadyManifestForRender } from "../../release-assets/manifest-cache.js";
 import { createEsmCache, createModuleCache, loadModule } from "./module-loader/index.js";
+import { isBuildFailure } from "./module-loader/build-failure.js";
 import { getCSSImports, runWithCSSCollector, } from "../../modules/react-loader/css-import-collector.js";
 import { assembleRenderResult } from "./render-result-assembly.js";
 import { isMdxEsmExportMismatchError, recoverStaleMdxEsmPreviewCaches } from "../page-rendering.js";
@@ -160,7 +161,11 @@ export class RenderPipeline {
                 continue;
             const errorMessage = result.error.message;
             if (result.type === "page") {
-                criticalFailures.push({ path: result.path, error: errorMessage });
+                criticalFailures.push({
+                    path: result.path,
+                    error: errorMessage,
+                    buildFailure: isBuildFailure(result.error),
+                });
                 renderPageLog.error("Critical page module failed to load", {
                     path: result.path,
                     error: errorMessage,
@@ -180,6 +185,10 @@ export class RenderPipeline {
                 detail: `Critical page module(s) failed to load:\n${failedDetails}`,
                 context: {
                     criticalFailures,
+                    // A module that never compiled is a developer-facing build failure;
+                    // one that compiled and threw at module scope is an application
+                    // error the project's own error page should present.
+                    buildFailure: criticalFailures.some((f) => f.buildFailure),
                     loadedCount: loaded.length,
                     totalModules: modules.length,
                 },

package/esm/src/routing/api/context-builder.d.ts

@@ -12,31 +12,42 @@ export interface APIContext {
     headers: Headers;
     url: URL;
     /**
-     * Read the request body as JSON, or build a JSON response.
+     * Build a JSON `Response`. `ctx.json(data, init?)` mirrors `Response.json`.
      *
-     * `ctx.json()` with no arguments parses and returns the request body.
-     * `ctx.json(data, init?)` returns a JSON `Response`.
+     * To read the request body, use `ctx.body()` or the raw `ctx.request.json()`.
      */
-    json: {
-        (): Promise<unknown>;
-        (data: unknown, init?: ResponseInit): Response;
-    };
+    json: (data: unknown, init?: ResponseInit) => Response;
+    /**
+     * Read and parse the request body as JSON.
+     *
+     * The result is cached, so calling it more than once (or alongside a manual
+     * `ctx.request.json()`) does not throw `Body already consumed`. A body that
+     * is not valid JSON becomes a 400, not an unhandled 500.
+     */
+    body: <T = unknown>() => Promise<T>;
     text: (data: string, init?: ResponseInit) => Response;
     fs: FileSystemAdapter;
 }
 /**
- * Build the `ctx.json` helper for a request.
- *
- * Overloaded on arity. `ctx.json(data)` builds a response; `ctx.json()` reads
- * the request body, which is what handlers reach for, and what the zero-arg
- * form was previously misread as. It used to stringify `undefined` into a
- * Response, so `await ctx.json()` yielded a Response object that serialised
- * back out as `{}` and silently dropped every posted payload.
+ * Build the `ctx.json` response helper. Writes only; mirrors `Response.json`.
  *
  * Exported because the isolation Worker builds its own context and has to
  * behave identically. Handlers must not care which one ran them.
  */
-export declare function createJsonHelper(request: Request): APIContext["json"];
+export declare function createJsonHelper(_request: Request): APIContext["json"];
+/**
+ * Build the `ctx.body` request-body reader.
+ *
+ * The parse is memoised on the first call, so a validation helper and a handler
+ * that both read the body do not fight over a single-use stream. The clone is
+ * taken up front, while the context is built, so `ctx.request` is left intact
+ * for a handler that still wants the raw stream — and, crucially, so a handler
+ * that reads `ctx.request` raw *before* calling `ctx.body()` cannot make the
+ * clone throw `Body already consumed` (`request.clone()` throws synchronously
+ * once the original stream is disturbed). A malformed body is turned into a
+ * catalogued 400 rather than escaping as a 500.
+ */
+export declare function createBodyReader(request: Request): APIContext["body"];
 export declare function createContext(request: Request, match: RouteMatch, fs: FileSystemAdapter): APIContext;
 /**
  * @deprecated Use {@link flattenRouteParams} directly. Kept as a thin alias so

package/esm/src/routing/api/context-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../../../../src/src/routing/api/context-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAG3D,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;IACT;;;;;OAKG;IACH,IAAI,EAAE;QACJ,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,QAAQ,CAAC;KAChD,CAAC;IACF,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,QAAQ,CAAC;IACtD,EAAE,EAAE,iBAAiB,CAAC;CACvB;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAUrE;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,iBAAiB,GACpB,UAAU,CAmBZ;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GACxC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB"}
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../../../../src/src/routing/api/context-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAI3D,OAAO,EAAE,YAAY,EAAE,CAAC;AAExB,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,OAAO,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;IAC1C,KAAK,EAAE,eAAe,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,GAAG,EAAE,GAAG,CAAC;IACT;;;;OAIG;IACH,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,QAAQ,CAAC;IACvD;;;;;;OAMG;IACH,IAAI,EAAE,CAAC,CAAC,GAAG,OAAO,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY,KAAK,QAAQ,CAAC;IACtD,EAAE,EAAE,iBAAiB,CAAC;CACvB;AAgBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAGtE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAAC,MAAM,CAAC,CAiBrE;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,iBAAiB,GACpB,UAAU,CAqBZ;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,GACxC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAExB"}

package/esm/src/routing/api/context-builder.js

@@ -1,4 +1,5 @@
 import { parseCookies } from "../../utils/cookie-utils.js";
+import { INVALID_ARGUMENT } from "../../errors/index.js";
 import { flattenRouteParams } from "../flatten-route-params.js";
 export { parseCookies };
 function createResponse(body, contentType, init) {
@@ -11,29 +12,46 @@ function createResponse(body, contentType, init) {
     });
 }
 /**
- * Build the `ctx.json` helper for a request.
- *
- * Overloaded on arity. `ctx.json(data)` builds a response; `ctx.json()` reads
- * the request body, which is what handlers reach for, and what the zero-arg
- * form was previously misread as. It used to stringify `undefined` into a
- * Response, so `await ctx.json()` yielded a Response object that serialised
- * back out as `{}` and silently dropped every posted payload.
+ * Build the `ctx.json` response helper. Writes only; mirrors `Response.json`.
  *
  * Exported because the isolation Worker builds its own context and has to
  * behave identically. Handlers must not care which one ran them.
  */
-export function createJsonHelper(request) {
-    function json(...args) {
-        if (args.length === 0)
-            return request.json();
-        const [data, init] = args;
-        return createResponse(JSON.stringify(data), "application/json", init);
-    }
-    return json;
+export function createJsonHelper(_request) {
+    return (data, init) => createResponse(JSON.stringify(data), "application/json", init);
+}
+/**
+ * Build the `ctx.body` request-body reader.
+ *
+ * The parse is memoised on the first call, so a validation helper and a handler
+ * that both read the body do not fight over a single-use stream. The clone is
+ * taken up front, while the context is built, so `ctx.request` is left intact
+ * for a handler that still wants the raw stream — and, crucially, so a handler
+ * that reads `ctx.request` raw *before* calling `ctx.body()` cannot make the
+ * clone throw `Body already consumed` (`request.clone()` throws synchronously
+ * once the original stream is disturbed). A malformed body is turned into a
+ * catalogued 400 rather than escaping as a 500.
+ */
+export function createBodyReader(request) {
+    // Clone eagerly: at construction time the original body is guaranteed
+    // untouched, so the read is order-independent with any raw `ctx.request`
+    // access a handler performs later.
+    const source = request.clone();
+    let parsed;
+    const read = () => {
+        if (!parsed) {
+            parsed = source.json().catch(() => {
+                throw INVALID_ARGUMENT.create({ detail: "Request body is not valid JSON" });
+            });
+        }
+        return parsed;
+    };
+    return () => read();
 }
 export function createContext(request, match, fs) {
     const url = new URL(request.url);
     const json = createJsonHelper(request);
+    const body = createBodyReader(request);
     const text = (data, init) => createResponse(data, "text/plain", init);
     return {
         request,
@@ -44,6 +62,7 @@ export function createContext(request, match, fs) {
         headers: request.headers,
         url,
         json,
+        body,
         text,
         fs,
     };

package/esm/src/routing/api/module-loader/loader.js

@@ -5,7 +5,7 @@ import { validateHTTPImports } from "./http-validator.js";
 import { loadSecurityConfig } from "./security-config.js";
 import { createError, toError } from "../../../errors/index.js";
 import { getEsbuildLoader } from "../../../utils/path-utils.js";
-import { createFileSystem } from "../../../platform/compat/fs.js";
+import { createFileSystem, realPath } from "../../../platform/compat/fs.js";
 import * as pathHelper from "../../../platform/compat/path/index.js";
 import { FILE_EXTENSIONS, getLoaderForFile, validateModulePath } from "./loader-helpers.js";
 import { isDeno } from "../../../platform/compat/runtime.js";
@@ -211,6 +211,61 @@ function createAdapterResolvePlugin(adapter, projectDir) {
         },
     };
 }
+/**
+ * Refuse to load any file the bundle resolved outside the project.
+ *
+ * The resolver plugins above validate the specifiers they claim, but esbuild
+ * applies the project's own tsconfig `paths` itself, before any `onResolve`
+ * callback runs. A templated project maps `@/*` to `./*`, so `@/../secrets.ts`
+ * is resolved by esbuild straight to a path above the project root and loaded
+ * in the default namespace, where none of those guards ever see it.
+ *
+ * This runs at load time instead, which is the one point every resolution
+ * strategy converges on. Returning `undefined` defers to normal loading, so the
+ * plugin only ever subtracts. Package code is exempt: `node_modules` is
+ * resolved by esbuild's own node resolution rather than by a project alias, and
+ * is legitimately hoisted above the project root in a monorepo.
+ *
+ * `roots` carries both the project path as configured and its symlink-resolved
+ * form, because esbuild reports the real path of a file it loaded. A project
+ * reached through a symlink (`/var` -> `/private/var` on macOS, and any deploy
+ * layout that symlinks a release directory) would otherwise fail every import.
+ */
+/**
+ * The project path as configured, plus its symlink-resolved form when they
+ * differ. `realPath` throws if the directory is missing, in which case the
+ * configured path is all there is to compare against.
+ */
+async function resolveProjectRoots(projectDir) {
+    const configured = pathHelper.resolve(projectDir);
+    try {
+        const real = await realPath(configured);
+        return real === configured ? [configured] : [configured, real];
+    }
+    catch {
+        return [configured];
+    }
+}
+function createProjectBoundaryPlugin(roots) {
+    return {
+        name: "vf-project-boundary",
+        setup(build) {
+            build.onLoad({ filter: /.*/ }, (args) => {
+                if (roots.some((root) => isWithinDirectory(root, args.path)))
+                    return undefined;
+                if (args.path.split(/[\\/]/).includes("node_modules"))
+                    return undefined;
+                logger.error(`[API] Resolved import escapes project: ${args.path}`);
+                return {
+                    errors: [{
+                            text: `Import escapes the project directory: ${args.path}. ` +
+                                `API routes may only import files inside the project.`,
+                        }],
+                };
+            });
+        },
+    };
+}
 function loadAndTranspileModule(modulePath, projectDir, adapter, fs, config) {
     return withSpan("api.loadAndTranspileModule", async () => {
         const { filePath: resolvedPath, contents: source } = await readFileWithExtensions(adapter, modulePath, FILE_EXTENSIONS, projectDir);
@@ -289,6 +344,7 @@ function loadAndTranspileModule(modulePath, projectDir, adapter, fs, config) {
                 createImportMapPlugin(projectDir, adapter, config),
                 createAdapterResolvePlugin(adapter, projectDir),
                 createHTTPPlugin({ allowedHosts, projectDir }),
+                createProjectBoundaryPlugin(await resolveProjectRoots(projectDir)),
             ],
         });
         if (result.errors?.length) {

package/esm/src/server/dev-server/middleware.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../../src/src/server/dev-server/middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAM7D,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAEnD,UAAU,qBAAqB;IAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAkFD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAkC/B;AAqHD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,EAAE,eAAe,EACvB,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAClD,OAAO,CAAC,IAAI,CAAC,CASf"}
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../../../src/src/server/dev-server/middleware.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yCAAyC,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAM7D,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAEnD,UAAU,qBAAqB;IAC7B,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAkFD,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAkC/B;AAgJD,wBAAsB,eAAe,CACnC,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,EAAE,eAAe,EACvB,cAAc,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAClD,OAAO,CAAC,IAAI,CAAC,CASf"}

package/esm/src/server/dev-server/middleware.js

@@ -136,25 +136,48 @@ async function loadMiddlewareFromVirtualFS(middlewarePath, adapter, strictExport
         await fs.remove(tempDir, { recursive: true });
     }
 }
+/** Describe the shape of the default export that was rejected. */
+function describeDefaultExport(exported) {
+    if (Array.isArray(exported)) {
+        if (exported.length === 0)
+            return `Found an empty default export array.`;
+        const badIndex = exported.findIndex((value) => typeof value !== "function");
+        if (badIndex >= 0) {
+            return `Found a default export array with a non-function at index ${badIndex} ` +
+                `(${typeof exported[badIndex]}).`;
+        }
+    }
+    if (exported && typeof exported === "object") {
+        const keys = Object.keys(exported);
+        return keys.length > 0
+            ? `Found a default export of type object with keys: ${keys.join(", ")}.`
+            : `Found a default export of type object with no keys.`;
+    }
+    return `Found a default export of type ${typeof exported}.`;
+}
 /**
  * Explain what a root middleware file must export. When the module looks like it
  * was written for Next.js, say so, because that is overwhelmingly why this
  * fails. A bad root middleware takes down every route, so the message has
  * to be enough to fix the file without reading the source.
  */
-function invalidMiddlewareExport(middlewareModule, sourceFile) {
+function invalidMiddlewareExport(middlewareModule, sourceFile, exported) {
     const named = middlewareModule && typeof middlewareModule === "object"
         ? Object.keys(middlewareModule)
         : [];
     const looksLikeNext = named.includes("middleware") &&
         typeof middlewareModule.middleware === "function";
+    const hasDefault = middlewareModule && typeof middlewareModule === "object" &&
+        "default" in middlewareModule;
     const detail = looksLikeNext
         ? `Found a named "middleware" export, which is the Next.js convention. ` +
             `Veryfront expects a default export, and its middleware receives ` +
             `(c, next), where c is a context carrying c.req, not the Request itself.`
-        : named.length > 0
-            ? `Found export(s): ${named.join(", ")}.`
-            : `The module has no usable export.`;
+        : hasDefault
+            ? describeDefaultExport(exported)
+            : named.length > 0
+                ? `Found export(s): ${named.join(", ")}.`
+                : `The module has no usable export.`;
     return new TypeError(`Invalid middleware export in ${sourceFile}. ${detail}\n` +
         `Expected a default export that is a middleware function, or a non-empty ` +
         `array of them:\n\n` +
@@ -171,7 +194,7 @@ function normalizeMiddlewareExport(middlewareModule, strict = false, sourceFile
         : middlewareModule;
     if (Array.isArray(exported)) {
         if (strict && (exported.length === 0 || exported.some((value) => typeof value !== "function"))) {
-            throw invalidMiddlewareExport(middlewareModule, sourceFile);
+            throw invalidMiddlewareExport(middlewareModule, sourceFile, exported);
         }
         return exported.filter((middleware) => typeof middleware === "function");
     }
@@ -179,7 +202,7 @@ function normalizeMiddlewareExport(middlewareModule, strict = false, sourceFile
         return [exported];
     }
     if (strict) {
-        throw invalidMiddlewareExport(middlewareModule, sourceFile);
+        throw invalidMiddlewareExport(middlewareModule, sourceFile, exported);
     }
     return [];
 }

package/esm/src/server/handlers/request/ssr/ssr.handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr.handler.d.ts","sourceRoot":"","sources":["../../../../../../src/src/server/handlers/request/ssr/ssr.handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAEf,aAAa,EACd,MAAM,gBAAgB,CAAC;AAWxB,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,4CAA4C,CAAC;AAOpD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAKzE;AA+BD,qBAAa,UAAW,SAAQ,WAAW;IACzC,QAAQ,EAAE,eAAe,CAIvB;IAEF,OAAO,CAAC,UAAU,CAAiB;gBAEvB,UAAU,CAAC,EAAE,cAAc;IAKvC,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA8BjE,OAAO,CAAC,qBAAqB;IAmF7B,OAAO,CAAC,iBAAiB;IAkEzB,OAAO,CAAC,cAAc;YAgBR,cAAc;YA6Bd,sBAAsB;YAgBtB,aAAa;CAU5B"}
+{"version":3,"file":"ssr.handler.d.ts","sourceRoot":"","sources":["../../../../../../src/src/server/handlers/request/ssr/ssr.handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAEf,aAAa,EACd,MAAM,gBAAgB,CAAC;AAWxB,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,4CAA4C,CAAC;AAOpD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAKzE;AAiCD,qBAAa,UAAW,SAAQ,WAAW;IACzC,QAAQ,EAAE,eAAe,CAIvB;IAEF,OAAO,CAAC,UAAU,CAAiB;gBAEvB,UAAU,CAAC,EAAE,cAAc;IAKvC,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA8BjE,OAAO,CAAC,qBAAqB;IAmF7B,OAAO,CAAC,iBAAiB;IAkEzB,OAAO,CAAC,cAAc;YAgBR,cAAc;YA6Bd,sBAAsB;YAgBtB,aAAa;CAU5B"}

package/esm/src/server/handlers/request/ssr/ssr.handler.js

@@ -49,9 +49,11 @@ export function isProductionMode(ctx, _url) {
  * opposed to errors thrown by the running application.
  *
  * Module-load failures arrive wrapped in a RUNTIME-category `render-error`,
- * which loses the original category, so they are identified by their
- * `criticalFailures` context instead: a page module that could not be *loaded*
- * always failed to compile or resolve.
+ * which loses the original category, so they carry a `buildFailure` flag that
+ * the module loader sets at the point of failure. Failing to load is not
+ * evidence on its own: a module that compiled fine and threw at module scope
+ * also fails to load, and that is an application error the project's own error
+ * page should present.
  */
 function isBuildError(error) {
     if (!(error instanceof VeryfrontError))
@@ -59,7 +61,7 @@ function isBuildError(error) {
     if (error.category === "BUILD" || error.category === "MODULE")
         return true;
     const context = error.context;
-    return Array.isArray(context?.criticalFailures) && context.criticalFailures.length > 0;
+    return context?.buildFailure === true;
 }
 export class SSRHandler extends BaseHandler {
     metadata = {

package/esm/src/skill/prompt-augmentation.d.ts

@@ -6,11 +6,13 @@
  * @module
  */
 import type { Skill } from "./types.js";
+/** Maximum number of skills rendered in an agent system prompt. */
+export declare const MAX_SKILL_MANIFEST_PROMPT_ENTRIES = 30;
 /**
  * Build the skill manifest prompt section for an agent's system prompt.
  *
- * Lists all available skills with their descriptions and instructions
- * on how to use the skill tools (load_skill, load_skill_reference, execute_skill_script).
+ * Lists up to the prompt entry limit with descriptions and instructions on
+ * how to use the skill tools (load_skill, load_skill_reference, execute_skill_script).
  *
  * @param skills - Map of resolved skills for the agent
  * @returns Prompt section string, or empty string if no skills

package/esm/src/skill/prompt-augmentation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-augmentation.d.ts","sourceRoot":"","sources":["../../../src/src/skill/prompt-augmentation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,CA4B3E"}
+{"version":3,"file":"prompt-augmentation.d.ts","sourceRoot":"","sources":["../../../src/src/skill/prompt-augmentation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,mEAAmE;AACnE,eAAO,MAAM,iCAAiC,KAAK,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,GAAG,MAAM,CA0C3E"}

package/esm/src/skill/prompt-augmentation.js

@@ -5,11 +5,13 @@
  *
  * @module
  */
+/** Maximum number of skills rendered in an agent system prompt. */
+export const MAX_SKILL_MANIFEST_PROMPT_ENTRIES = 30;
 /**
  * Build the skill manifest prompt section for an agent's system prompt.
  *
- * Lists all available skills with their descriptions and instructions
- * on how to use the skill tools (load_skill, load_skill_reference, execute_skill_script).
+ * Lists up to the prompt entry limit with descriptions and instructions on
+ * how to use the skill tools (load_skill, load_skill_reference, execute_skill_script).
  *
  * @param skills - Map of resolved skills for the agent
  * @returns Prompt section string, or empty string if no skills
@@ -23,8 +25,17 @@ export function buildSkillManifestPrompt(skills) {
         "You have access to skills via tool calling. IMPORTANT: You MUST call the load_skill tool (not write it as text) to activate a skill before performing skill-related tasks.",
         "",
     ];
+    let displayedSkillCount = 0;
     for (const [id, skill] of skills) {
         lines.push(`- **${id}**: ${skill.metadata.description}`);
+        displayedSkillCount += 1;
+        if (displayedSkillCount === MAX_SKILL_MANIFEST_PROMPT_ENTRIES) {
+            break;
+        }
+    }
+    if (skills.size > MAX_SKILL_MANIFEST_PROMPT_ENTRIES) {
+        lines.push("");
+        lines.push(`${skills.size - MAX_SKILL_MANIFEST_PROMPT_ENTRIES} more skill summaries omitted from this prompt. Call load_skill only with a known skill ID.`);
     }
     lines.push("");
     lines.push("### Skill Tools (call these as tools, never write them as text)");