veryfront 0.1.1152 → 0.1.1153

package/esm/src/platform/adapters/fs/veryfront/websocket-manager.js

@@ -506,32 +506,45 @@ export class WebSocketManager {
                 parentDirs: Array.from(parentDirs),
                 prefixes: ["file:", "stat:", "dir:"],
             });
-            this.deps.invalidationCallbacks.invalidateModulePaths?.(changedPaths);
             const projectId = this.deps.client.getProjectId();
+            const invalidations = [
+                this.deps.invalidationCallbacks.invalidateModulePaths?.(changedPaths),
+            ];
             logger.debug("Clearing SSR module cache for HMR", {
                 changedPaths,
                 projectId,
                 usePerProject: !!this.deps.invalidationCallbacks.clearSSRModuleCacheForProject,
             });
             if (this.deps.invalidationCallbacks.clearSSRModuleCacheForProject && projectId) {
-                this.deps.invalidationCallbacks.clearSSRModuleCacheForProject(projectId);
+                invalidations.push(this.deps.invalidationCallbacks.clearSSRModuleCacheForProject(projectId));
             }
             else {
-                this.deps.invalidationCallbacks.clearSSRModuleCache?.();
+                invalidations.push(this.deps.invalidationCallbacks.clearSSRModuleCache?.());
+            }
+            if (projectId) {
+                if (this.deps.invalidationCallbacks.clearRouterDetectionCacheForProject) {
+                    invalidations.push(this.deps.invalidationCallbacks.clearRouterDetectionCacheForProject(projectId));
+                }
+                if (this.deps.invalidationCallbacks.clearProjectDiscoveryCacheForProject) {
+                    invalidations.push(this.deps.invalidationCallbacks.clearProjectDiscoveryCacheForProject(projectId));
+                }
             }
             if (this.deps.invalidationCallbacks.clearRendererCacheForProject && projectId) {
-                await this.deps.invalidationCallbacks.clearRendererCacheForProject(projectId);
+                invalidations.push(this.deps.invalidationCallbacks.clearRendererCacheForProject(projectId));
             }
             if (this.deps.invalidationCallbacks.clearProjectCSSCache && this.deps.projectSlug) {
-                this.deps.invalidationCallbacks.clearProjectCSSCache(this.deps.projectSlug);
+                invalidations.push(this.deps.invalidationCallbacks.clearProjectCSSCache(this.deps.projectSlug));
+            }
+            const pendingInvalidations = invalidations.filter((invalidation) => invalidation !== undefined);
+            if (pendingInvalidations.length > 0) {
+                await Promise.all(pendingInvalidations);
             }
             if (contentContext?.sourceType === "branch") {
                 await this.deps.cache.deleteByPrefixAsync("files:branch:");
                 try {
                     const files = await this.deps.client.listAllFiles();
                     const cacheKey = buildFileListCacheKey(contentContext);
-                    await this.deps.setFileListCache(cacheKey, files);
-                    this.deps.clearFileListIndex();
+                    await this.deps.replaceSourceSnapshot(cacheKey, files);
                     preparedStyleArtifact = await this.deps.pregenerateStyles?.(files);
                     logger.debug("Fresh files cached (memory + Redis)", {
                         cacheKey,
@@ -597,24 +610,34 @@ export class WebSocketManager {
             this.deps.clearMemoryCaches();
             this.deps.invalidationCallbacks.clearDomainCache?.();
             const projectId = this.deps.client.getProjectId();
+            const invalidations = [];
             if (this.deps.invalidationCallbacks.clearSSRModuleCacheForProject && projectId) {
-                this.deps.invalidationCallbacks.clearSSRModuleCacheForProject(projectId);
+                invalidations.push(this.deps.invalidationCallbacks.clearSSRModuleCacheForProject(projectId));
             }
             else {
-                this.deps.invalidationCallbacks.clearSSRModuleCache?.();
+                invalidations.push(this.deps.invalidationCallbacks.clearSSRModuleCache?.());
             }
-            if (this.deps.invalidationCallbacks.clearRouterDetectionCacheForProject && projectId) {
-                this.deps.invalidationCallbacks.clearRouterDetectionCacheForProject(projectId);
+            if (projectId) {
+                if (this.deps.invalidationCallbacks.clearRouterDetectionCacheForProject) {
+                    invalidations.push(this.deps.invalidationCallbacks.clearRouterDetectionCacheForProject(projectId));
+                }
+                if (this.deps.invalidationCallbacks.clearProjectDiscoveryCacheForProject) {
+                    invalidations.push(this.deps.invalidationCallbacks.clearProjectDiscoveryCacheForProject(projectId));
+                }
             }
-            this.deps.invalidationCallbacks.clearModulePathCache?.();
+            invalidations.push(this.deps.invalidationCallbacks.clearModulePathCache?.());
             if (this.deps.invalidationCallbacks.clearSnippetCacheForProject && this.deps.projectSlug) {
-                this.deps.invalidationCallbacks.clearSnippetCacheForProject(this.deps.projectSlug);
+                invalidations.push(this.deps.invalidationCallbacks.clearSnippetCacheForProject(this.deps.projectSlug));
             }
             if (this.deps.invalidationCallbacks.clearRendererCacheForProject && projectId) {
-                await this.deps.invalidationCallbacks.clearRendererCacheForProject(projectId);
+                invalidations.push(this.deps.invalidationCallbacks.clearRendererCacheForProject(projectId));
             }
             if (this.deps.invalidationCallbacks.clearProjectCSSCache && this.deps.projectSlug) {
-                this.deps.invalidationCallbacks.clearProjectCSSCache(this.deps.projectSlug);
+                invalidations.push(this.deps.invalidationCallbacks.clearProjectCSSCache(this.deps.projectSlug));
+            }
+            const pendingInvalidations = invalidations.filter((invalidation) => invalidation !== undefined);
+            if (pendingInvalidations.length > 0) {
+                await Promise.all(pendingInvalidations);
             }
             const totalFileCount = fileBranchCount + fileReleaseCount + fileEnvCount;
             const totalStatCount = statBranchCount + statReleaseCount + statEnvCount;
@@ -630,8 +653,7 @@ export class WebSocketManager {
                 try {
                     const files = await this.deps.client.listAllFiles();
                     const cacheKey = buildFileListCacheKey(contentContext);
-                    await this.deps.setFileListCache(cacheKey, files);
-                    this.deps.clearFileListIndex();
+                    await this.deps.replaceSourceSnapshot(cacheKey, files);
                     preparedStyleArtifact = await this.deps.pregenerateStyles?.(files);
                     logger.debug("FRESH FILES FETCHED", {
                         cacheKey,

package/esm/src/platform/adapters/fs/wrapper.d.ts

@@ -35,6 +35,8 @@ export declare class NotSupportedError extends Error {
 export declare class FSAdapterWrapper implements ExtendedFileSystemAdapter {
     private readonly _fsAdapter;
     readonly refreshSourceSnapshot?: (reason?: string) => Promise<void>;
+    readonly ensureSourceSnapshotFresh?: (reason?: string) => Promise<void>;
+    readonly getSourceSnapshotVersion?: () => number | undefined | Promise<number | undefined>;
     constructor(fsAdapter: FSAdapter);
     getUnderlyingAdapter(): FSAdapter;
     getAdapterType(): string;

package/esm/src/platform/adapters/fs/wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../../../../../src/src/platform/adapters/fs/wrapper.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../../../../../src/src/platform/adapters/fs/wrapper.ts"],"names":[],"mappings":"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"}

package/esm/src/platform/adapters/fs/wrapper.js

@@ -37,11 +37,19 @@ function isContextualAdapter(adapter) {
 export class FSAdapterWrapper {
     _fsAdapter;
     refreshSourceSnapshot;
+    ensureSourceSnapshotFresh;
+    getSourceSnapshotVersion;
     constructor(fsAdapter) {
         this._fsAdapter = fsAdapter;
         if (typeof fsAdapter.refreshSourceSnapshot === "function") {
             this.refreshSourceSnapshot = (reason) => fsAdapter.refreshSourceSnapshot.call(fsAdapter, reason);
         }
+        if (typeof fsAdapter.ensureSourceSnapshotFresh === "function") {
+            this.ensureSourceSnapshotFresh = (reason) => fsAdapter.ensureSourceSnapshotFresh.call(fsAdapter, reason);
+        }
+        if (typeof fsAdapter.getSourceSnapshotVersion === "function") {
+            this.getSourceSnapshotVersion = () => fsAdapter.getSourceSnapshotVersion.call(fsAdapter);
+        }
     }
     getUnderlyingAdapter() {
         return this._fsAdapter;

package/esm/src/rendering/app-route-resolver.js

@@ -6,7 +6,7 @@
  * - Dynamic segment matching ([id], [...slug], etc.)
  * - Page file loading with frontmatter extraction
  */
-import { isDynamicSegment } from "../utils/route-path-utils.js";
+import { isCatchAllSegment, isDynamicSegment } from "../utils/route-path-utils.js";
 import { join } from "../platform/compat/path/index.js";
 import { extract } from "../platform/compat/std/front-matter-yaml.js";
 export async function getAppRouteEntity(projectDir, slug, adapter, appDirName = "app") {
@@ -53,22 +53,11 @@ async function tryDynamicMatch(projectDir, slug, adapter, appDirName) {
     const segments = slug ? slug.split("/").filter(Boolean) : [];
     let currentDir = join(projectDir, appDirName);
     for (const segment of segments) {
-        const exactPath = join(currentDir, segment);
-        try {
-            const stat = await adapter.fs.stat(exactPath);
-            if (stat.isDirectory) {
-                currentDir = exactPath;
-                continue;
-            }
-        }
-        catch (_) {
-            /* expected: exact path may not exist, try dynamic segments */
-        }
-        const dynamic = await findDynamicDir(currentDir, adapter);
-        if (!dynamic)
+        const routeDirectory = await findRouteDirectory(currentDir, segment, adapter);
+        if (!routeDirectory)
             return null;
-        currentDir = join(currentDir, dynamic.name);
-        if (dynamic.isCatchAll)
+        currentDir = join(currentDir, routeDirectory.name);
+        if (routeDirectory.isCatchAll)
             break;
     }
     for (const ext of [".mdx", ".md", ".tsx", ".jsx", ".ts", ".js"]) {
@@ -79,14 +68,23 @@ async function tryDynamicMatch(projectDir, slug, adapter, appDirName) {
     }
     return null;
 }
-async function findDynamicDir(dir, adapter) {
+async function findRouteDirectory(dir, segment, adapter) {
     try {
         const entries = await adapter.fs.readDir(dir);
+        let dynamic = null;
         for await (const entry of entries) {
-            if (!entry.isDirectory || !isDynamicSegment(entry.name))
+            if (!entry.isDirectory && !entry.isSymlink)
                 continue;
-            return { name: entry.name, isCatchAll: entry.name.startsWith("[...") };
+            if (entry.name === segment)
+                return { name: entry.name, isCatchAll: false };
+            if (!dynamic && isDynamicSegment(entry.name)) {
+                dynamic = {
+                    name: entry.name,
+                    isCatchAll: isCatchAllSegment(entry.name),
+                };
+            }
         }
+        return dynamic;
     }
     catch (_) {
         /* expected: adapter.fs.readDir may fail for npm compatibility */

package/esm/src/rendering/router-detection.js

@@ -6,7 +6,7 @@
  * - Directory structure analysis
  * - Route file presence detection
  **************************/
-import { isAbsolute, join, normalize, relative } from "../platform/compat/path/index.js";
+import { basename, dirname, isAbsolute, join, normalize, relative } from "../platform/compat/path/index.js";
 import { createFileSystem } from "../platform/compat/fs.js";
 import { rendererLogger } from "../utils/index.js";
 import { LRUCache } from "../utils/lru-wrapper.js";
@@ -113,14 +113,12 @@ export async function detectAppRouter(projectDir, config, adapter, options) {
 async function detectAppRouterImpl(projectDir, config, adapter) {
     const appDirName = config?.directories?.app ?? "app";
     const pagesDirName = config?.directories?.pages ?? "pages";
-    const appDir = join(projectDir, appDirName);
-    const pagesDir = join(projectDir, pagesDirName);
-    const [appStat, pagesStat] = await Promise.all([
-        statWithFallback(appDir, adapter),
-        statWithFallback(pagesDir, adapter),
+    const appDir = normalize(join(projectDir, appDirName));
+    const pagesDir = normalize(join(projectDir, pagesDirName));
+    const [hasAppDir, hasPagesDir] = await Promise.all([
+        directoryExists(appDir, projectDir, adapter),
+        directoryExists(pagesDir, projectDir, adapter),
     ]);
-    const hasAppDir = Boolean(appStat?.isDirectory);
-    const hasPagesDir = Boolean(pagesStat?.isDirectory);
     if (hasAppDir && (await hasRouteFiles(appDir, adapter)))
         return true;
     if (hasPagesDir && (await hasRouteFiles(pagesDir, adapter)))
@@ -131,7 +129,23 @@ async function detectAppRouterImpl(projectDir, config, adapter) {
 }
 const ROUTE_EXTENSIONS = new Set([".mdx", ".md", ".tsx", ".jsx", ".ts", ".js"]);
 const ROUTE_PATTERNS = ["page", "layout", "error", "loading", "not-found", "index"];
-async function hasRouteFiles(dir, adapter) {
+async function resolveTraversalKey(dir, adapter, requireCanonicalPath) {
+    if (!adapter.fs.realPath) {
+        return requireCanonicalPath ? null : normalize(dir);
+    }
+    try {
+        return normalize(await adapter.fs.realPath(dir));
+    }
+    catch (_) {
+        /* expected: virtual adapters may not resolve physical paths */
+        return requireCanonicalPath ? null : normalize(dir);
+    }
+}
+async function hasRouteFiles(dir, adapter, visited = new Set(), requireCanonicalPath = false) {
+    const traversalKey = await resolveTraversalKey(dir, adapter, requireCanonicalPath);
+    if (traversalKey === null || visited.has(traversalKey))
+        return false;
+    visited.add(traversalKey);
     const entries = await readDirWithFallback(dir, adapter);
     for (const entry of entries) {
         if (entry.isFile) {
@@ -143,7 +157,12 @@ async function hasRouteFiles(dir, adapter) {
             }
             continue;
         }
-        if (entry.isDirectory && (await hasRouteFiles(join(dir, entry.name), adapter))) {
+        if (entry.isDirectory &&
+            (await hasRouteFiles(join(dir, entry.name), adapter, visited))) {
+            return true;
+        }
+        if (entry.isSymlink &&
+            (await hasRouteFiles(join(dir, entry.name), adapter, visited, true))) {
             return true;
         }
     }
@@ -164,6 +183,18 @@ async function withAdapterFallback(adapterFn, fallbackFn, defaultValue) {
         }
     }
 }
+async function directoryExists(path, projectDir, adapter) {
+    if (normalize(path) === normalize(projectDir))
+        return true;
+    const parentEntries = await readDirWithFallback(dirname(path), adapter);
+    const directoryName = basename(path);
+    const listed = parentEntries.some((entry) => entry.name === directoryName && (entry.isDirectory || entry.isSymlink));
+    if (listed || adapter.id !== "cloudflare")
+        return listed;
+    // Cloudflare KV represents directories only as key prefixes, so its parent
+    // listing can omit a directory that stat can still resolve.
+    return Boolean((await statWithFallback(path, adapter))?.isDirectory);
+}
 async function statWithFallback(path, adapter) {
     const fs = createFileSystem();
     return await withAdapterFallback(async () => (await adapter.fs.stat(path)), async () => {

package/esm/src/server/handlers/request/agent-stream.handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-stream.handler.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/handlers/request/agent-stream.handler.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAGpF,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,wCAAwC,CAAC;AAchD,OAAO,EACL,4BAA4B,EAE7B,MAAM,2CAA2C,CAAC;AA0BnD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAkBnG,MAAM,WAAW,sBACf,SAAQ,yBAAyB,EAAE,+BAA+B;IAClE,4BAA4B,CAAC,EAAE,OAAO,4BAA4B,CAAC;IACnE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,+BAA+B,CAAC,YAAY,CAAC,CAAC;CACpF;AAugBD,qBAAa,kBAAmB,SAAQ,WAAW;IASrC,OAAO,CAAC,QAAQ,CAAC,IAAI;IARjC,QAAQ,EAAE,eAAe,CAMvB;gBAE2B,IAAI,GAAE,sBAAoC;IAIvE,OAAO,CAAC,sBAAsB;IAsBxB,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CA6NxE"}
+{"version":3,"file":"agent-stream.handler.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/handlers/request/agent-stream.handler.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,yBAAyB,EAAE,MAAM,oCAAoC,CAAC;AAGpF,OAAO,EAEL,KAAK,+BAA+B,EACrC,MAAM,wCAAwC,CAAC;AAchD,OAAO,EACL,4BAA4B,EAE7B,MAAM,2CAA2C,CAAC;AA0BnD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAkBnG,MAAM,WAAW,sBACf,SAAQ,yBAAyB,EAAE,+BAA+B;IAClE,4BAA4B,CAAC,EAAE,OAAO,4BAA4B,CAAC;IACnE,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,+BAA+B,CAAC,YAAY,CAAC,CAAC;CACpF;AAwgBD,qBAAa,kBAAmB,SAAQ,WAAW;IASrC,OAAO,CAAC,QAAQ,CAAC,IAAI;IARjC,QAAQ,EAAE,eAAe,CAMvB;gBAE2B,IAAI,GAAE,sBAAoC;IAIvE,OAAO,CAAC,sBAAsB;IAsBxB,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CA6NxE"}

package/esm/src/server/handlers/request/agent-stream.handler.js

@@ -232,6 +232,7 @@ async function resolveAgentSourceConfig(ctx, sourceContext) {
     if (!cacheKey) {
         throw new Error("Explicit agent source requires a project identity");
     }
+    await ctx.adapter.fs.ensureSourceSnapshotFresh?.("agent-source-config");
     return await getConfig(ctx.projectDir, ctx.adapter, {
         cacheKey,
         sourceContext: buildAgentSourceRunOptions(sourceContext),

package/esm/src/server/handlers/request/api/api-handler-wrapper.d.ts

@@ -9,5 +9,6 @@ export declare class ApiHandlerWrapper extends BaseHandler {
     initialize(): Promise<void>;
     handle(req: Request, ctx: HandlerContext): Promise<HandlerResult>;
     private handleWithContext;
+    private isPageRequest;
 }
 //# sourceMappingURL=api-handler-wrapper.d.ts.map

package/esm/src/server/handlers/request/api/api-handler-wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api-handler-wrapper.d.ts","sourceRoot":"","sources":["../../../../../../src/src/server/handlers/request/api/api-handler-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAEf,aAAa,EACd,MAAM,gBAAgB,CAAC;AAsBxB,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAiE;IAChF,OAAO,CAAC,WAAW,CAA8B;IAEjD,QAAQ,EAAE,eAAe,CAGvB;gBAGA,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,uCAAuC,EAAE,cAAc;IAOnE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAmDvE,OAAO,CAAC,iBAAiB;CA2D1B"}
+{"version":3,"file":"api-handler-wrapper.d.ts","sourceRoot":"","sources":["../../../../../../src/src/server/handlers/request/api/api-handler-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAEf,aAAa,EACd,MAAM,gBAAgB,CAAC;AA2BxB,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAiE;IAChF,OAAO,CAAC,WAAW,CAA8B;IAEjD,QAAQ,EAAE,eAAe,CAGvB;gBAGA,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,uCAAuC,EAAE,cAAc;IAOnE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAW3B,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;YAmDzD,iBAAiB;YAkFjB,aAAa;CAuB5B"}

package/esm/src/server/handlers/request/api/api-handler-wrapper.js

@@ -1,8 +1,9 @@
 import { BaseHandler } from "../../response/base.js";
-import { getApiHandler, withApiHandler } from "./pages-api-handler.js";
+import { ensurePreviewSourceSnapshotFresh, getApiHandler, withApiHandler, } from "./pages-api-handler.js";
 import { PRIORITY_MEDIUM_API } from "../../../../utils/constants/index.js";
 import { withSpan } from "../../../../observability/tracing/otlp-setup.js";
 import { ensureProjectDiscovery } from "./project-discovery.js";
+import { PageResolver } from "../../../../rendering/page-resolution/page-resolver.js";
 export class ApiHandlerWrapper extends BaseHandler {
     projectDir;
     adapter;
@@ -54,13 +55,27 @@ export class ApiHandlerWrapper extends BaseHandler {
             environmentName: ctx.environmentName,
         });
     }
-    handleWithContext(req, ctx, pathname) {
+    async handleWithContext(req, ctx, pathname) {
         return withSpan("api.handleWithContext", async () => {
             try {
+                // WebSocket pokes update mutable previews immediately. This bounded,
+                // coalesced check is the fallback for missed pokes and establishes
+                // one source snapshot for route and primitive discovery.
+                await ensurePreviewSourceSnapshotFresh(ctx);
+                const canResolveAsPage = pathname !== "/api" &&
+                    !pathname.startsWith("/api/") &&
+                    (req.method === "GET" || req.method === "HEAD");
+                let isPageRequest = false;
+                if (canResolveAsPage) {
+                    isPageRequest = await this.isPageRequest(pathname, ctx);
+                }
+                if (isPageRequest) {
+                    return this.continue();
+                }
                 // Lazy per-project primitive discovery (agents, tools) on first access.
                 // Must run within runWithContext so VFS and registry scope are correct.
                 await ensureProjectDiscovery(ctx);
-                const apiRes = await withApiHandler(ctx, (api) => api.handle(req, ctx));
+                const apiRes = await withApiHandler(ctx, (api) => api.handle(req, ctx), { sourceSnapshotReady: true });
                 if (!apiRes) {
                     this.logDebug("[API-Wrapper] API handler returned null, continuing to next handler", { pathname }, ctx);
                     return this.continue();
@@ -88,4 +103,23 @@ export class ApiHandlerWrapper extends BaseHandler {
             "api.projectSlug": ctx.projectSlug ?? "unknown",
         });
     }
+    async isPageRequest(pathname, ctx) {
+        const slug = pathname === "/" ? "" : pathname.replace(/^\/+|\/+$/g, "");
+        const pageResolver = new PageResolver({
+            projectDir: ctx.projectDir,
+            projectId: ctx.projectId,
+            config: ctx.config ?? {},
+            adapter: ctx.adapter,
+        });
+        try {
+            return await pageResolver.pageExists(slug);
+        }
+        catch (error) {
+            this.logDebug("[API-Wrapper] Page ownership is indeterminate; preserving API discovery", {
+                pathname,
+                error: this.getErrorMessage(error),
+            }, ctx);
+            return false;
+        }
+    }
 }

package/esm/src/server/handlers/request/api/pages-api-handler.d.ts

@@ -31,13 +31,18 @@ export declare class LRUHandlerCache<T> implements HandlerCache<T> {
     values(): IterableIterator<T>;
 }
 export declare function __injectCacheForTests(cache: HandlerCache<Promise<APIRouteHandler>> | null): void;
+export declare function ensurePreviewSourceSnapshotFresh(ctx: HandlerContext): Promise<void>;
+export declare function refreshPreviewSourceSnapshot(ctx: HandlerContext): Promise<void>;
+interface ApiHandlerOptions {
+    sourceSnapshotReady?: boolean;
+}
 export declare function getApiHandler(ctx: HandlerContext): Promise<APIRouteHandler>;
 /**
  * Use an API handler while holding a lease that defers cache-eviction cleanup.
  * The lease begins before the handler promise is awaited, closing the gap
  * between a cache lookup and APIRouteHandler.handle() registering the request.
  */
-export declare function withApiHandler<T>(ctx: HandlerContext, use: (handler: APIRouteHandler) => T | Promise<T>): Promise<T>;
+export declare function withApiHandler<T>(ctx: HandlerContext, use: (handler: APIRouteHandler) => T | Promise<T>, options?: ApiHandlerOptions): Promise<T>;
 export declare function resetApiHandler(projectDir?: string): Promise<void>;
 /**
  * Reset cached API handlers for a specific project slug.
@@ -47,4 +52,5 @@ export declare function resetApiHandler(projectDir?: string): Promise<void>;
  * all entries and destroy those scoped to the project slug.
  */
 export declare function resetApiHandlerForProject(projectSlug: string): Promise<void>;
+export {};
 //# sourceMappingURL=pages-api-handler.d.ts.map

package/esm/src/server/handlers/request/api/pages-api-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pages-api-handler.d.ts","sourceRoot":"","sources":["../../../../../../src/src/server/handlers/request/api/pages-api-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAO/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACzC,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAC/B;AAID,qBAAa,eAAe,CAAC,CAAC,CAAE,YAAW,YAAY,CAAC,CAAC,CAAC;IACxD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,uBAAuB,CAAS;gBAGtC,OAAO,GAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;KACzB;IAUR,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAG/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAGhC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAU5B,KAAK,IAAI,IAAI;IAQb,OAAO,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAGvC,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC;CAG/B;AAqBD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,GAAG,IAAI,GACnD,IAAI,CAEN;AAiHD,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAEjF;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAChD,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,wBAAsB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAaxE;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAcf"}
+{"version":3,"file":"pages-api-handler.d.ts","sourceRoot":"","sources":["../../../../../../src/src/server/handlers/request/api/pages-api-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAO/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;IAChC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,KAAK,IAAI,IAAI,CAAC;IACd,OAAO,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC;IACzC,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC;CAC/B;AAID,qBAAa,eAAe,CAAC,CAAC,CAAE,YAAW,YAAY,CAAC,CAAC,CAAC;IACxD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,uBAAuB,CAAS;gBAGtC,OAAO,GAAE;QACP,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;KACzB;IAUR,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAG/B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAGhC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAU5B,KAAK,IAAI,IAAI;IAQb,OAAO,IAAI,gBAAgB,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAGvC,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC;CAG/B;AAqBD,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,YAAY,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,GAAG,IAAI,GACnD,IAAI,CAEN;AA8BD,wBAAsB,gCAAgC,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAUzF;AAED,wBAAsB,4BAA4B,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAGrF;AAED,UAAU,iBAAiB;IACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAyFD,wBAAsB,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAEjF;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EACjD,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,CAAC,CAAC,CAUZ;AAED,wBAAsB,eAAe,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAaxE;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/esm/src/server/handlers/request/api/pages-api-handler.js

@@ -91,17 +91,33 @@ function shouldCacheApiHandler(ctx) {
     // Cannot confirm a production context → do not cache.
     return getApiHandlerCacheContext(ctx)?.mode === "production";
 }
-async function refreshPreviewSourceSnapshot(ctx) {
+function hasMutablePreviewSource(ctx) {
     if (!ctx.projectSlug)
-        return;
+        return false;
     const cacheContext = getApiHandlerCacheContext(ctx);
     // Skip when production, or when the context is indeterminate.
-    if (!cacheContext || cacheContext.mode === "production")
+    return !!cacheContext && cacheContext.mode !== "production";
+}
+export async function ensurePreviewSourceSnapshotFresh(ctx) {
+    if (!hasMutablePreviewSource(ctx))
+        return;
+    if (ctx.adapter.fs.ensureSourceSnapshotFresh) {
+        await ctx.adapter.fs.ensureSourceSnapshotFresh("preview-request-routing");
+        return;
+    }
+    // Backward compatibility for custom remote adapters that only implement the
+    // original unconditional refresh contract.
+    await refreshPreviewSourceSnapshot(ctx);
+}
+export async function refreshPreviewSourceSnapshot(ctx) {
+    if (!hasMutablePreviewSource(ctx))
         return;
     await ctx.adapter.fs.refreshSourceSnapshot?.("preview-api-route-discovery");
 }
-async function createApiHandler(ctx) {
-    await refreshPreviewSourceSnapshot(ctx);
+async function createApiHandler(ctx, options = {}) {
+    if (!options.sourceSnapshotReady) {
+        await ensurePreviewSourceSnapshotFresh(ctx);
+    }
     const handler = new APIRouteHandler(ctx.projectDir, ctx.adapter);
     await handler.initialize();
     return handler;
@@ -156,15 +172,15 @@ function retainHandler(promise) {
         }
     };
 }
-function getApiHandlerPromise(ctx) {
+function getApiHandlerPromise(ctx, options = {}) {
     if (!shouldCacheApiHandler(ctx)) {
-        return { promise: createApiHandler(ctx), cached: false };
+        return { promise: createApiHandler(ctx, options), cached: false };
     }
     const cache = getCache();
     const key = getCacheKey(ctx);
     let promise = cache.get(key);
     if (!promise) {
-        promise = createApiHandler(ctx);
+        promise = createApiHandler(ctx, options);
         cache.set(key, promise);
     }
     return { promise, cached: true };
@@ -177,8 +193,8 @@ export async function getApiHandler(ctx) {
  * The lease begins before the handler promise is awaited, closing the gap
  * between a cache lookup and APIRouteHandler.handle() registering the request.
  */
-export async function withApiHandler(ctx, use) {
-    const { promise, cached } = getApiHandlerPromise(ctx);
+export async function withApiHandler(ctx, use, options = {}) {
+    const { promise, cached } = getApiHandlerPromise(ctx, options);
     const release = retainHandler(promise);
     try {
         return await use(await promise);

package/esm/src/server/handlers/request/api/project-discovery.d.ts

@@ -7,4 +7,10 @@ import type { HandlerContext } from "../../types.js";
  * correct project scope.
  */
 export declare function ensureProjectDiscovery(ctx: HandlerContext): Promise<DiscoveryResult>;
+/**
+ * Drop completed and in-flight discovery records for every source scope owned
+ * by a project. The next scoped request rebuilds registries transactionally
+ * from its current source snapshot.
+ */
+export declare function clearProjectDiscoveryCacheForProject(projectId: string): void;
 //# sourceMappingURL=project-discovery.d.ts.map

package/esm/src/server/handlers/request/api/project-discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"project-discovery.d.ts","sourceRoot":"","sources":["../../../../../../src/src/server/handlers/request/api/project-discovery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAOtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAyHrD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAoF1F"}
+{"version":3,"file":"project-discovery.d.ts","sourceRoot":"","sources":["../../../../../../src/src/server/handlers/request/api/project-discovery.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAOtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AA4HrD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAyG1F;AAED;;;;GAIG;AACH,wBAAgB,oCAAoC,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAM5E"}

package/esm/src/server/handlers/request/api/project-discovery.js

@@ -68,15 +68,17 @@ function discoveryKey(ctx) {
     if (registryScope) {
         return registryScope.scopeId;
     }
-    const slug = ctx.projectSlug ?? ctx.projectDir;
+    const projectIdentity = ctx.projectId ?? ctx.projectSlug ?? ctx.projectDir;
     const environment = ctx.enriched?.environment ?? ctx.resolvedEnvironment ??
         (ctx.releaseId ? "production" : "preview");
     if (environment === "production") {
-        return ctx.releaseId ? `${slug}:release:${ctx.releaseId}` : `${slug}:production:unreleased`;
+        return ctx.releaseId
+            ? `${projectIdentity}:release:${ctx.releaseId}`
+            : `${projectIdentity}:production:unreleased`;
     }
     const branch = ctx.requestContext?.branch ?? ctx.enriched?.branch ?? ctx.parsedDomain?.branch ??
         "main";
-    return `${slug}:preview:${branch}`;
+    return `${projectIdentity}:preview:${branch}`;
 }
 function shouldCacheCompletedDiscovery(ctx) {
     const registryScope = tryGetRegistryScopeContext();
@@ -94,17 +96,24 @@ function shouldCacheCompletedDiscovery(ctx) {
  * correct project scope.
  */
 export async function ensureProjectDiscovery(ctx) {
+    await ctx.adapter.fs.ensureSourceSnapshotFresh?.("primitive-discovery");
     const key = discoveryKey(ctx);
-    const cacheCompletedDiscovery = shouldCacheCompletedDiscovery(ctx);
+    const sourceSnapshotVersion = await ctx.adapter.fs.getSourceSnapshotVersion?.();
+    const cacheCompletedDiscovery = shouldCacheCompletedDiscovery(ctx) ||
+        sourceSnapshotVersion !== undefined;
     const existing = discoveredProjects.get(key);
-    if (existing)
+    if (existing &&
+        (sourceSnapshotVersion === undefined ||
+            existing.sourceSnapshotVersion === sourceSnapshotVersion)) {
         return existing.promise;
+    }
     const discovery = {
+        sourceSnapshotVersion,
         promise: (async () => {
-            const { clearTranspileCache, discoverAll } = await import("../../../../discovery/index.js");
-            const { agentRegistry } = await import("../../../../agent/composition/composition.js");
-            const { toolRegistry } = await import("../../../../tool/registry.js");
             return await runWithRegistryTransaction(async () => {
+                const { clearTranspileCache, discoverAll } = await import("../../../../discovery/index.js");
+                const { agentRegistry } = await import("../../../../agent/composition/composition.js");
+                const { toolRegistry } = await import("../../../../tool/registry.js");
                 // Clear stale entries in a transaction-local copy. Concurrent runs keep
                 // using the prior live registry until discovery succeeds and the staged
                 // replacement is committed atomically.
@@ -146,11 +155,22 @@ export async function ensureProjectDiscovery(ctx) {
     };
     discoveredProjects.set(key, discovery);
     try {
-        return await discovery.promise;
+        const result = await discovery.promise;
+        if (result.errors.length > 0) {
+            const current = discoveredProjects.get(key);
+            if (current === discovery) {
+                discoveredProjects.delete(key);
+            }
+        }
+        return result;
     }
     catch (error) {
-        // Allow retry on next request
-        discoveredProjects.delete(key);
+        // A superseded generation may already own this key. Delete only our own
+        // record so the newer discovery remains reusable after it completes.
+        const current = discoveredProjects.get(key);
+        if (current === discovery) {
+            discoveredProjects.delete(key);
+        }
         logger.warn("Primitive discovery failed (will retry)", {
             projectSlug: ctx.projectSlug,
             error: error instanceof Error ? error.message : String(error),
@@ -170,3 +190,15 @@ export async function ensureProjectDiscovery(ctx) {
         }
     }
 }
+/**
+ * Drop completed and in-flight discovery records for every source scope owned
+ * by a project. The next scoped request rebuilds registries transactionally
+ * from its current source snapshot.
+ */
+export function clearProjectDiscoveryCacheForProject(projectId) {
+    for (const key of discoveredProjects.keys()) {
+        if (key === projectId || key.startsWith(`${projectId}:`)) {
+            discoveredProjects.delete(key);
+        }
+    }
+}

package/esm/src/server/runtime-handler/adapter-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter-factory.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/adapter-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAQ9D,UAAU,uBAAuB;IAC/B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,OAAO,EAAE,cAAc,CAAC;IACxB,kCAAkC;IAClC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,yDAAyD;IACzD,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,UAAU,wBAAwB;IAChC;;;OAGG;IACH,GAAG,EAAE,OAAO,CAAC;IACb,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,OAAO,EAAE,cAAc,CAAC;IACxB,6BAA6B;IAC7B,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,mBAAmB;IACnB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,iBAAiB;IACjB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,kBAAkB;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,iBAAiB;IACjB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,uCAAuC;IACvC,QAAQ,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IAC/C,kBAAkB;IAClB,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,yCAAyC;IACzC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,yBAAyB;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qEAAqE;IACrE,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B;AASD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,uBAAuB,CAAC,CA8IlC"}
+{"version":3,"file":"adapter-factory.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/adapter-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG7D,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAQ9D,UAAU,uBAAuB;IAC/B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,OAAO,EAAE,cAAc,CAAC;IACxB,kCAAkC;IAClC,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,yDAAyD;IACzD,cAAc,EAAE,OAAO,CAAC;CACzB;AAED,UAAU,wBAAwB;IAChC;;;OAGG;IACH,GAAG,EAAE,OAAO,CAAC;IACb,6BAA6B;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,OAAO,EAAE,cAAc,CAAC;IACxB,6BAA6B;IAC7B,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,mBAAmB;IACnB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,iBAAiB;IACjB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,kBAAkB;IAClB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,iBAAiB;IACjB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,uCAAuC;IACvC,QAAQ,EAAE,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;IAC/C,kBAAkB;IAClB,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClC,yCAAyC;IACzC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,yBAAyB;IACzB,YAAY,EAAE,YAAY,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,qEAAqE;IACrE,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B;AASD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,uBAAuB,CAAC,CAiJlC"}