veryfront 0.1.73 → 0.1.74

package/esm/src/server/runtime-handler/index.js

@@ -67,6 +67,108 @@ import { SCANNER_PATH_PATTERN } from "../../utils/constants/security.js";
 export { parseProxyEnvironment } from "./proxy-environment.js";
 const baseLogger = getBaseLogger("SERVER");
 const logger = baseLogger.component("runtime-handler");
+/** Handler names in registration order. */
+export const HANDLER_NAMES = [
+    "AuthHandler",
+    "CsrfHandler",
+    "HMRHandler",
+    "CorsHandler",
+    "HealthHandler",
+    "MetricsHandler",
+    "MemoryDebugHandler",
+    "ClientLogHandler",
+    "DevEndpointsHandler",
+    "StylesCSSHandler",
+    "DebugContextHandler",
+    "OpenAPIHandler",
+    "OpenAPIDocsHandler",
+    "InternalAgentsListHandler",
+    "AgentStreamHandler",
+    "AgentRunResumeHandler",
+    "AgentRunCancelHandler",
+    "ChannelInvokeHandler",
+    "DevDashboardHandler",
+    "ProjectsHandler",
+    "StudioBridgeModulesHandler",
+    "CSSHandler",
+    "DevFileHandler",
+    "SnippetHandler",
+    "StaticHandler",
+    "LibModulesHandler",
+    "RSCHandler",
+    "ModuleHandler",
+    "ApiHandlerWrapper",
+    "MarkdownPreviewHandler",
+    "SSRHandler",
+    "NotFoundHandler",
+];
+/** Factory for each handler. Only called when no override is provided (lazy instantiation). */
+const handlerFactories = {
+    AuthHandler: () => new AuthHandler(),
+    CsrfHandler: () => new CsrfHandler(),
+    HMRHandler: () => new HMRHandler(),
+    CorsHandler: () => new CorsHandler(),
+    HealthHandler: () => new HealthHandler(),
+    MetricsHandler: () => new MetricsHandler(),
+    MemoryDebugHandler: () => new MemoryDebugHandler(),
+    ClientLogHandler: () => new ClientLogHandler(),
+    DevEndpointsHandler: () => new DevEndpointsHandler(),
+    StylesCSSHandler: () => new StylesCSSHandler(),
+    DebugContextHandler: () => new DebugContextHandler(),
+    OpenAPIHandler: () => new OpenAPIHandler(),
+    OpenAPIDocsHandler: () => new OpenAPIDocsHandler(),
+    InternalAgentsListHandler: () => new InternalAgentsListHandler(),
+    AgentStreamHandler: () => new AgentStreamHandler(),
+    AgentRunResumeHandler: () => new AgentRunResumeHandler(),
+    AgentRunCancelHandler: () => new AgentRunCancelHandler(),
+    ChannelInvokeHandler: () => new ChannelInvokeHandler(),
+    DevDashboardHandler: () => new DevDashboardHandler(),
+    ProjectsHandler: () => new ProjectsHandler(),
+    StudioBridgeModulesHandler: () => new StudioBridgeModulesHandler(),
+    CSSHandler: () => new CSSHandler(),
+    DevFileHandler: () => new DevFileHandler(),
+    SnippetHandler: () => new SnippetHandler(),
+    StaticHandler: () => new StaticHandler(),
+    LibModulesHandler: () => new LibModulesHandler(),
+    RSCHandler: () => new RSCHandler(),
+    ModuleHandler: () => new ModuleHandler(),
+    ApiHandlerWrapper: (projectDir, adapter) => new ApiHandlerWrapper(projectDir, adapter),
+    MarkdownPreviewHandler: () => new MarkdownPreviewHandler(),
+    SSRHandler: () => new SSRHandler(),
+    NotFoundHandler: () => new NotFoundHandler(),
+};
+/**
+ * Creates a RouteRegistry populated with the standard handler chain.
+ *
+ * Handlers are instantiated lazily — overridden slots skip construction
+ * of the default handler entirely.
+ *
+ * @param projectDir - Root project directory
+ * @param adapter - Runtime adapter for environment access
+ * @param deps - Optional dependency overrides for testing
+ * @returns Object containing the registry and the api handler (for initialization)
+ */
+export function createHandlerRegistry(projectDir, adapter, deps = {}) {
+    const registry = new RouteRegistry({
+        debug: deps.debug,
+        enableMetrics: true,
+    });
+    const overrides = deps.overrides ?? {};
+    // Create the ApiHandlerWrapper first — it's special because callers need
+    // the returned instance for initialization regardless of overrides.
+    const apiHandler = overrides.ApiHandlerWrapper
+        ? overrides.ApiHandlerWrapper
+        : new ApiHandlerWrapper(projectDir, adapter);
+    const handlers = HANDLER_NAMES.map((name) => {
+        if (name === "ApiHandlerWrapper")
+            return apiHandler;
+        if (overrides[name])
+            return overrides[name];
+        return handlerFactories[name](projectDir, adapter);
+    });
+    registry.registerAll(handlers);
+    return { registry, apiHandler };
+}
 export function createVeryfrontHandler(projectDir, adapter, opts = { projectDir }) {
     const isDebugEnabled = !!(opts.debug || adapter.env.get("VERYFRONT_DEBUG"));
     function logDebug(message, extra) {
@@ -109,45 +211,9 @@ export function createVeryfrontHandler(projectDir, adapter, opts = { projectDir
             return undefined;
         }
     })();
-    const registry = new RouteRegistry({
+    const { registry, apiHandler } = createHandlerRegistry(projectDir, adapter, {
         debug: opts.debug,
-        enableMetrics: true,
     });
-    const apiHandler = new ApiHandlerWrapper(projectDir, adapter);
-    registry.registerAll([
-        new AuthHandler(),
-        new CsrfHandler(),
-        new HMRHandler(),
-        new CorsHandler(),
-        new HealthHandler(),
-        new MetricsHandler(),
-        new MemoryDebugHandler(),
-        new ClientLogHandler(),
-        new DevEndpointsHandler(),
-        new StylesCSSHandler(),
-        new DebugContextHandler(),
-        new OpenAPIHandler(),
-        new OpenAPIDocsHandler(),
-        new InternalAgentsListHandler(),
-        new AgentStreamHandler(),
-        new AgentRunResumeHandler(),
-        new AgentRunCancelHandler(),
-        new ChannelInvokeHandler(),
-        new DevDashboardHandler(),
-        new ProjectsHandler(),
-        new StudioBridgeModulesHandler(),
-        new CSSHandler(),
-        new DevFileHandler(),
-        new SnippetHandler(),
-        new StaticHandler(),
-        new LibModulesHandler(),
-        new RSCHandler(),
-        new ModuleHandler(),
-        apiHandler,
-        new MarkdownPreviewHandler(),
-        new SSRHandler(),
-        new NotFoundHandler(),
-    ]);
     const isProxyMode = opts.config?.fs?.veryfront?.proxyMode === true;
     const readyPromise = isProxyMode ? Promise.resolve() : apiHandler.initialize().catch((error) => {
         logger.error("API handler initialization failed", {

package/esm/src/server/runtime-handler/local-project-discovery.d.ts

@@ -8,19 +8,47 @@
  */
 import type { RuntimeAdapter } from "../../platform/adapters/base.js";
 import { LRUCache } from "../../utils/lru-wrapper.js";
-/** Cache of local adapters by project directory */
+/**
+ * Injectable cache container for project discovery state.
+ *
+ * Wraps both the project-path cache (slug → absolute path) and the
+ * adapter cache (project dir → RuntimeAdapter) so that callers — especially
+ * tests — can supply an isolated instance instead of sharing global state.
+ */
+export declare class ProjectDiscoveryCache {
+    /** Cache of discovered local project paths by slug */
+    readonly projects: LRUCache<string, string>;
+    /** Cache of local adapters by project directory */
+    readonly adapters: LRUCache<string, RuntimeAdapter>;
+    constructor(opts?: {
+        maxProjects?: number;
+        maxAdapters?: number;
+    });
+    /** Clear both caches */
+    clear(): void;
+}
+/** Default module-level cache instance (backward-compatible singleton) */
+export declare const defaultDiscoveryCache: ProjectDiscoveryCache;
+/**
+ * @deprecated Use `defaultDiscoveryCache.adapters` instead.
+ * Kept for backward compatibility with existing consumers.
+ */
 export declare const localAdapterCache: LRUCache<string, RuntimeAdapter>;
+/**
+ * @deprecated Use `defaultDiscoveryCache.projects` instead.
+ * Kept for backward compatibility with existing consumers.
+ */
+export declare const localProjectCache: LRUCache<string, string>;
 /** Standard directories to search for local projects */
 export declare const standardProjectDirs: string[];
-/** Cache of discovered local project paths by slug */
-export declare const localProjectCache: LRUCache<string, string>;
 /**
  * Find the local filesystem path for a project by slug.
  *
  * @param slug - The project slug to find
  * @param adapter - The runtime adapter to use for filesystem operations
  * @param headerPath - Optional path from x-project-path header (takes precedence)
+ * @param cache - Optional cache instance (defaults to module-level singleton)
  * @returns The absolute path to the project, or undefined if not found
  */
-export declare function findLocalProjectPath(slug: string, adapter: RuntimeAdapter, headerPath?: string): Promise<string | undefined>;
+export declare function findLocalProjectPath(slug: string, adapter: RuntimeAdapter, headerPath?: string, cache?: ProjectDiscoveryCache): Promise<string | undefined>;
 //# sourceMappingURL=local-project-discovery.d.ts.map

package/esm/src/server/runtime-handler/local-project-discovery.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-project-discovery.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/local-project-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAOtD,mDAAmD;AACnD,eAAO,MAAM,iBAAiB,kCAE5B,CAAC;AAKH,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,UAAgC,CAAC;AAEjE,sDAAsD;AACtD,eAAO,MAAM,iBAAiB,0BAE5B,CAAC;AAyCH;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA+C7B"}
+{"version":3,"file":"local-project-discovery.d.ts","sourceRoot":"","sources":["../../../../src/src/server/runtime-handler/local-project-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAOtD;;;;;;GAMG;AACH,qBAAa,qBAAqB;IAChC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;gBAExC,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;IASjE,wBAAwB;IACxB,KAAK,IAAI,IAAI;CAId;AAED,0EAA0E;AAC1E,eAAO,MAAM,qBAAqB,uBAA8B,CAAC;AAMjE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,kCAAiC,CAAC;AAEhE;;;GAGG;AACH,eAAO,MAAM,iBAAiB,0BAAiC,CAAC;AAEhE,wDAAwD;AACxD,eAAO,MAAM,mBAAmB,UAAgC,CAAC;AAsCjE;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,cAAc,EACvB,UAAU,CAAC,EAAE,MAAM,EACnB,KAAK,GAAE,qBAA6C,GACnD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA+C7B"}

package/esm/src/server/runtime-handler/local-project-discovery.js

@@ -12,20 +12,49 @@ import { LRUCache } from "../../utils/lru-wrapper.js";
 import { registerLRUCache } from "../../cache/index.js";
 const baseLogger = getBaseLogger("SERVER");
 const logger = baseLogger.component("runtime-handler");
-/** Cache of local adapters by project directory */
-export const localAdapterCache = new LRUCache({
-    maxEntries: 50,
-});
-// Register cache for monitoring
-registerLRUCache("local-adapter-cache", localAdapterCache);
+/**
+ * Injectable cache container for project discovery state.
+ *
+ * Wraps both the project-path cache (slug → absolute path) and the
+ * adapter cache (project dir → RuntimeAdapter) so that callers — especially
+ * tests — can supply an isolated instance instead of sharing global state.
+ */
+export class ProjectDiscoveryCache {
+    /** Cache of discovered local project paths by slug */
+    projects;
+    /** Cache of local adapters by project directory */
+    adapters;
+    constructor(opts) {
+        this.projects = new LRUCache({
+            maxEntries: opts?.maxProjects ?? 100,
+        });
+        this.adapters = new LRUCache({
+            maxEntries: opts?.maxAdapters ?? 50,
+        });
+    }
+    /** Clear both caches */
+    clear() {
+        this.projects.clear();
+        this.adapters.clear();
+    }
+}
+/** Default module-level cache instance (backward-compatible singleton) */
+export const defaultDiscoveryCache = new ProjectDiscoveryCache();
+// Register the default caches for monitoring
+registerLRUCache("local-project-cache", defaultDiscoveryCache.projects);
+registerLRUCache("local-adapter-cache", defaultDiscoveryCache.adapters);
+/**
+ * @deprecated Use `defaultDiscoveryCache.adapters` instead.
+ * Kept for backward compatibility with existing consumers.
+ */
+export const localAdapterCache = defaultDiscoveryCache.adapters;
+/**
+ * @deprecated Use `defaultDiscoveryCache.projects` instead.
+ * Kept for backward compatibility with existing consumers.
+ */
+export const localProjectCache = defaultDiscoveryCache.projects;
 /** Standard directories to search for local projects */
 export const standardProjectDirs = ["data/projects", "projects"];
-/** Cache of discovered local project paths by slug */
-export const localProjectCache = new LRUCache({
-    maxEntries: 100,
-});
-// Register cache for monitoring
-registerLRUCache("local-project-cache", localProjectCache);
 function isNotFoundError(error) {
     if (!(error instanceof Error))
         return false;
@@ -68,9 +97,10 @@ async function isValidLocalProjectPath(path, adapter) {
  * @param slug - The project slug to find
  * @param adapter - The runtime adapter to use for filesystem operations
  * @param headerPath - Optional path from x-project-path header (takes precedence)
+ * @param cache - Optional cache instance (defaults to module-level singleton)
  * @returns The absolute path to the project, or undefined if not found
  */
-export async function findLocalProjectPath(slug, adapter, headerPath) {
+export async function findLocalProjectPath(slug, adapter, headerPath, cache = defaultDiscoveryCache) {
     if (headerPath) {
         try {
             const normalizedPath = headerPath.trim();
@@ -78,7 +108,7 @@ export async function findLocalProjectPath(slug, adapter, headerPath) {
                 const absolutePath = normalizedPath.startsWith("/")
                     ? normalizedPath
                     : `${cwd()}/${normalizedPath}`;
-                localProjectCache.set(slug, absolutePath);
+                cache.projects.set(slug, absolutePath);
                 return absolutePath;
             }
             logger.warn("Ignoring invalid x-project-path override", {
@@ -94,7 +124,7 @@ export async function findLocalProjectPath(slug, adapter, headerPath) {
             });
         }
     }
-    const cached = localProjectCache.get(slug);
+    const cached = cache.projects.get(slug);
     if (cached)
         return cached;
     for (const dir of standardProjectDirs) {
@@ -103,7 +133,7 @@ export async function findLocalProjectPath(slug, adapter, headerPath) {
             if (!await isValidLocalProjectPath(projectPath, adapter))
                 continue;
             const absolutePath = projectPath.startsWith("/") ? projectPath : `${cwd()}/${projectPath}`;
-            localProjectCache.set(slug, absolutePath);
+            cache.projects.set(slug, absolutePath);
             logger.debug("Discovered local project", { slug, path: absolutePath });
             return absolutePath;
         }

package/esm/src/server/services/rendering/ssr.service.d.ts

@@ -2,6 +2,22 @@ import * as dntShim from "../../../../_dnt.shims.js";
 import type { HandlerContext } from "../../handlers/types.js";
 import { type RendererAdapter } from "../../shared/renderer-factory.js";
 import type { CacheRepository } from "../../../repositories/types.js";
+/**
+ * Provides a renderer for a given handler context.
+ * Extracted to allow dependency injection in tests.
+ */
+export interface RendererProvider {
+    getRenderer(ctx: HandlerContext): Promise<RendererAdapter>;
+}
+/**
+ * Minimal interface for SSRService consumers (e.g., SSRHandler).
+ * Allows dependency injection and mocking in tests.
+ */
+export interface SSRServiceLike {
+    checkMemoryPressure(): MemoryStatus;
+    renderPage(ctx: HandlerContext, options: SSRRenderOptions): Promise<SSRRenderResult>;
+    createMemoryPressureResult(slug: string): SSRRenderResult;
+}
 export interface SSRRenderResult {
     status: number;
     html?: string;
@@ -31,10 +47,12 @@ export interface MemoryStatus {
     heapLimitMB: number;
     heapUsedPercent: number;
 }
-export declare class SSRService {
+export declare class SSRService implements SSRServiceLike {
     private readonly cacheRepo?;
+    private readonly rendererProvider;
     constructor(options?: {
         cacheRepo?: CacheRepository<string>;
+        rendererProvider?: RendererProvider;
     });
     checkMemoryPressure(): MemoryStatus;
     getRenderer(ctx: HandlerContext): Promise<RendererAdapter>;

package/esm/src/server/services/rendering/ssr.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ssr.service.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/services/rendering/ssr.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,2BAA2B,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,kCAAkC,CAAC;AAmB1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAItE,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,SAAS,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,SAAS,CAAC;IACpE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC;IACzB,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA0B;gBAEzC,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC,CAAA;KAAE;IAI7D,mBAAmB,IAAI,YAAY;IAW7B,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAI1D,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAiG1F,OAAO,CAAC,iBAAiB;IA4FzB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe;CAS1D"}
+{"version":3,"file":"ssr.service.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/services/rendering/ssr.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,2BAA2B,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,kCAAkC,CAAC;AAmB1C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAItE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAC5D;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,mBAAmB,IAAI,YAAY,CAAC;IACpC,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACrF,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC;CAC3D;AAUD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IACpC,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,SAAS,CAAC,EAAE,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,SAAS,CAAC;IACpE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC;IACzB,GAAG,EAAE,GAAG,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,OAAO,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,UAAW,YAAW,cAAc;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA0B;IACrD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmB;gBAExC,OAAO,CAAC,EAAE;QACpB,SAAS,CAAC,EAAE,eAAe,CAAC,MAAM,CAAC,CAAC;QACpC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;KACrC;IAKD,mBAAmB,IAAI,YAAY;IAW7B,WAAW,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAI1D,UAAU,CAAC,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAiG1F,OAAO,CAAC,iBAAiB;IA4FzB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe;CAS1D"}

package/esm/src/server/services/rendering/ssr.service.js

@@ -10,10 +10,18 @@ import { ErrorOverlay, parseErrorLocation } from "../../dev-server/error-overlay
 import { ErrorPages } from "../../utils/error-html.js";
 import { HTTP_INTERNAL_SERVER_ERROR, HTTP_NOT_FOUND, HTTP_OK, HTTP_UNAVAILABLE, } from "../../../utils/constants/index.js";
 const logger = serverLogger.component("ssr-service");
+/**
+ * Default RendererProvider that delegates to the real getRendererForProject.
+ */
+const defaultRendererProvider = {
+    getRenderer: (ctx) => timeAsync("renderer-init", () => getRendererForProject(ctx)),
+};
 export class SSRService {
     cacheRepo;
+    rendererProvider;
     constructor(options) {
         this.cacheRepo = options?.cacheRepo;
+        this.rendererProvider = options?.rendererProvider ?? defaultRendererProvider;
     }
     checkMemoryPressure() {
         const stats = getHeapStats();
@@ -25,7 +33,7 @@ export class SSRService {
         };
     }
     async getRenderer(ctx) {
-        return timeAsync("renderer-init", () => getRendererForProject(ctx));
+        return this.rendererProvider.getRenderer(ctx);
     }
     async renderPage(ctx, options) {
         const { request, url, slug, nonce, studioEmbed, projectId, pageId, noHmr, useNoCache } = options;

package/esm/src/server/shared/renderer/adapter.d.ts

@@ -9,6 +9,7 @@
  **************************/
 import * as dntShim from "../../../../_dnt.shims.js";
 import type { HandlerContext } from "../../handlers/types.js";
+import { type Renderer, type RendererOptions } from "../../../rendering/renderer.js";
 import type { PageDataResponse, RenderOptions, RenderResult } from "../../../rendering/orchestrator/types.js";
 import type { MdxBundle } from "../../../types/index.js";
 export interface RendererAdapter {
@@ -28,6 +29,30 @@ export interface RendererAdapter {
     compileMDX(content: string, frontmatter?: Record<string, unknown>, filePath?: string): Promise<MdxBundle>;
     destroy(): Promise<void>;
 }
+/**
+ * Abstraction over renderer initialization, allowing tests to inject
+ * a mock renderer without pulling in the full rendering subsystem.
+ */
+export interface RendererInitializer {
+    initialize(options: RendererOptions): Promise<Renderer>;
+    isInitialized(): boolean;
+    get(): Renderer;
+    destroy(): Promise<void>;
+}
+/**
+ * Replace the renderer initializer used by the adapter layer.
+ * Pass `undefined` to restore the default (real) initializer.
+ *
+ * Returns a disposer that restores the previous initializer — use in
+ * `afterEach` or with `using` to prevent test pollution:
+ *
+ * ```ts
+ * afterEach(() => setRendererInitializer(undefined));
+ * ```
+ *
+ * @internal Test-only — not part of the public API.
+ */
+export declare function setRendererInitializer(initializer?: RendererInitializer): void;
 export declare function getRendererForProject(ctx: HandlerContext): Promise<RendererAdapter>;
 export declare function destroyRendererAdapter(): Promise<void>;
 //# sourceMappingURL=adapter.d.ts.map

package/esm/src/server/shared/renderer/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/shared/renderer/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;4BAQ4B;AAC5B,OAAO,KAAK,OAAO,MAAM,2BAA2B,CAAC;AAMrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAY9D,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACb,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAYzD,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACzE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClF,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjC,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,IAAI,IAAI,CAAC;IACtB,sBAAsB,IAAI;QACxB,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;QAC7D,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC1E,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAChF,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAC/B,KAAK,IAAI,IAAI,CAAC;KACf,CAAC;IACF,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,UAAU,CACR,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,SAAS,CAAC,CAAC;IACtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAkND,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAiCzF;AAED,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAG5D"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/shared/renderer/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;4BAQ4B;AAC5B,OAAO,KAAK,OAAO,MAAM,2BAA2B,CAAC;AAMrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAE9D,OAAO,EAOL,KAAK,QAAQ,EACb,KAAK,eAAe,EACrB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EACV,gBAAgB,EAChB,aAAa,EACb,YAAY,EACb,MAAM,0CAA0C,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAYzD,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IACzE,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAClF,WAAW,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACjC,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,aAAa,IAAI,IAAI,CAAC;IACtB,sBAAsB,IAAI;QACxB,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;QAC7D,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC1E,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAChF,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAC/B,KAAK,IAAI,IAAI,CAAC;KACf,CAAC;IACF,oBAAoB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,UAAU,CACR,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,SAAS,CAAC,CAAC;IACtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACxD,aAAa,IAAI,OAAO,CAAC;IACzB,GAAG,IAAI,QAAQ,CAAC;IAChB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AA0CD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,CAAC,EAAE,mBAAmB,GAChC,IAAI,CAgBN;AAyND,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAiCzF;AAED,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAW5D"}

package/esm/src/server/shared/renderer/adapter.js

@@ -10,12 +10,72 @@ const logger = rendererLogger.component("renderer-adapter");
 const RENDER_CACHE_TTL_SECONDS = 3_600;
 /** Maximum entries for the local render cache layer */
 const RENDER_CACHE_LOCAL_MAX_ENTRIES = 200;
-let rendererInitPromise = null;
+/**
+ * Default initializer that delegates to the real shared renderer
+ * singleton from `#veryfront/rendering/renderer.ts`.
+ */
+const defaultInitializer = {
+    initialize: initializeRenderer,
+    isInitialized: isRendererInitialized,
+    get: getRenderer,
+    destroy: destroySharedRenderer,
+};
+let activeInitializer = defaultInitializer;
+let rendererInitState = null;
+function scheduleInitializerDestroy(initializer, pendingPromise) {
+    const destroy = async () => {
+        try {
+            await initializer.destroy();
+        }
+        catch (error) {
+            logger.warn("Failed to destroy renderer initializer", {
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    };
+    if (pendingPromise) {
+        void pendingPromise
+            .catch(() => undefined)
+            .then(destroy);
+        return;
+    }
+    if (!initializer.isInitialized())
+        return;
+    void destroy();
+}
+/**
+ * Replace the renderer initializer used by the adapter layer.
+ * Pass `undefined` to restore the default (real) initializer.
+ *
+ * Returns a disposer that restores the previous initializer — use in
+ * `afterEach` or with `using` to prevent test pollution:
+ *
+ * ```ts
+ * afterEach(() => setRendererInitializer(undefined));
+ * ```
+ *
+ * @internal Test-only — not part of the public API.
+ */
+export function setRendererInitializer(initializer) {
+    const nextInitializer = initializer ?? defaultInitializer;
+    const previous = activeInitializer;
+    const previousPendingPromise = rendererInitState?.initializer === previous
+        ? rendererInitState.promise
+        : undefined;
+    activeInitializer = nextInitializer;
+    if (rendererInitState?.initializer !== activeInitializer) {
+        rendererInitState = null;
+    }
+    if (previous !== activeInitializer) {
+        scheduleInitializerDestroy(previous, previousPendingPromise);
+    }
+}
 async function getOrInitRenderer() {
-    if (isRendererInitialized())
-        return getRenderer();
-    if (rendererInitPromise)
-        return rendererInitPromise;
+    if (activeInitializer.isInitialized())
+        return activeInitializer.get();
+    if (rendererInitState?.initializer === activeInitializer) {
+        return rendererInitState.promise;
+    }
     const isProxyMode = getEnvBoolean("PROXY_MODE", false, {
         trueValues: ["1"],
         trim: false,
@@ -42,12 +102,19 @@ async function getOrInitRenderer() {
         hasApiUrl: !!apiBaseUrl,
         cacheType: useApiCache ? "api-distributed" : "memory",
     });
-    rendererInitPromise = initializeRenderer(options);
+    const initializer = activeInitializer;
+    const initPromise = initializer.initialize(options);
+    rendererInitState = {
+        initializer,
+        promise: initPromise,
+    };
     try {
-        return await rendererInitPromise;
+        return await initPromise;
     }
     finally {
-        rendererInitPromise = null;
+        if (rendererInitState?.promise === initPromise) {
+            rendererInitState = null;
+        }
     }
 }
 function resolveEnvironment(ctx) {
@@ -210,6 +277,12 @@ export async function getRendererForProject(ctx) {
     return new RendererAdapterImpl(renderer, renderCtx);
 }
 export async function destroyRendererAdapter() {
-    await destroySharedRenderer();
-    rendererInitPromise = null;
+    const pendingPromise = rendererInitState?.initializer === activeInitializer
+        ? rendererInitState.promise
+        : undefined;
+    rendererInitState = null;
+    if (pendingPromise) {
+        await pendingPromise.catch(() => undefined);
+    }
+    await activeInitializer.destroy();
 }

package/esm/src/server/shared/renderer/index.d.ts

@@ -3,6 +3,6 @@
  *
  * @module server/shared/renderer
  */
-export { destroyRendererAdapter, getRendererForProject, type RendererAdapter } from "./adapter.js";
+export { destroyRendererAdapter, getRendererForProject, type RendererAdapter, type RendererInitializer, setRendererInitializer, } from "./adapter.js";
 export { shouldRejectDueToMemory } from "./memory/pressure.js";
 //# sourceMappingURL=index.d.ts.map

package/esm/src/server/shared/renderer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/shared/renderer/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AACnG,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/src/server/shared/renderer/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,sBAAsB,GACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC"}

package/esm/src/server/shared/renderer/index.js

@@ -3,5 +3,5 @@
  *
  * @module server/shared/renderer
  */
-export { destroyRendererAdapter, getRendererForProject } from "./adapter.js";
+export { destroyRendererAdapter, getRendererForProject, setRendererInitializer, } from "./adapter.js";
 export { shouldRejectDueToMemory } from "./memory/pressure.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.73",
+  "version": "0.1.74",
   "description": "The simplest way to build AI-powered apps",
   "keywords": [
     "react",

package/src/cli/commands/knowledge/command-help.ts

@@ -3,7 +3,7 @@ import type { CommandHelp } from "../../help/types.js";
 export const knowledgeHelp: CommandHelp = {
   name: "knowledge",
   description: "Ingest documents into the project knowledge base",
-  usage: "veryfront knowledge ingest <source> [options]",
+  usage: "veryfront knowledge ingest <source...> [options]",
   options: [
     {
       flag: "--project, -p <slug>",
@@ -28,6 +28,7 @@ export const knowledgeHelp: CommandHelp = {
   ],
   examples: [
     "veryfront knowledge ingest uploads/contracts/q1.pdf --json",
+    "veryfront knowledge ingest uploads/contracts/a.pdf uploads/contracts/b.pdf uploads/contracts/c.pdf --json",
     "veryfront knowledge ingest /workspace/uploads/q1.pdf --json",
     "veryfront knowledge ingest --path uploads/ --all --json",
   ],
@@ -36,5 +37,6 @@ export const knowledgeHelp: CommandHelp = {
     "`uploads/...` means a remote project upload; use `./uploads/...` or `/workspace/uploads/...` to force a local file",
     "`ingest` orchestrates upload resolution, parsing, and project file writes",
     "Requires python3; non-text formats also require the supported parser packages unless you run inside the Veryfront sandbox",
+    "The Veryfront sandbox image includes `kreuzberg`, and knowledge ingest falls back to the built-in parser when `kreuzberg` is unavailable or extraction fails",
   ],
 };