veryfront 0.1.216 → 0.1.217

package/src/src/extensions/factory-loader.ts

@@ -0,0 +1,76 @@
+/**
+ * Dynamic factory loader.
+ *
+ * Loads an extension factory from a filesystem path by dynamic import,
+ * invokes it, and wraps the result as a `ResolvedExtension`.
+ *
+ * @module extensions/factory-loader
+ */
+
+import { isAbsolute, toFileUrl } from "../../deps/jsr.io/@std/path/1.1.4/mod.js";
+import { EXTENSION_VALIDATION_ERROR } from "./errors.js";
+import type { Extension, ExtensionFactory, ExtensionSource, ResolvedExtension } from "./types.js";
+
+/**
+ * Dynamically import an extension factory from `path` and resolve it.
+ *
+ * `path` may be either an absolute filesystem path (for project and
+ * local-file sources) or a bare module specifier (for `package` source).
+ * Absolute paths are converted to `file://` URLs; bare specifiers are
+ * passed through so the runtime's module resolver can find them.
+ *
+ * The module must `export default` an `ExtensionFactory` (a function that
+ * returns an `Extension`). On any error — missing default export, default
+ * export that is not a function, factory throw, or import failure — this
+ * throws `EXTENSION_VALIDATION_ERROR` with a `detail` field that names the
+ * path and what went wrong.
+ *
+ * @param path Absolute filesystem path or bare module specifier.
+ * @param source Where the extension was discovered (drives merge priority).
+ * @param config Optional config forwarded to the factory.
+ */
+export async function loadExtensionFactory(
+  path: string,
+  source: ExtensionSource,
+  config?: unknown,
+): Promise<ResolvedExtension> {
+  const specifier = isAbsolute(path) ? toFileUrl(path).href : path;
+  let mod: { default?: unknown };
+  try {
+    mod = await import(specifier);
+  } catch (err) {
+    throw EXTENSION_VALIDATION_ERROR.create({
+      detail: `Failed to import extension at "${path}": ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      cause: err,
+    });
+  }
+
+  const factory = mod.default;
+  if (factory === undefined || factory === null) {
+    throw EXTENSION_VALIDATION_ERROR.create({
+      detail: `Extension at "${path}" has no default export`,
+    });
+  }
+
+  if (typeof factory !== "function") {
+    throw EXTENSION_VALIDATION_ERROR.create({
+      detail: `Extension at "${path}" default export is not a function (got ${typeof factory})`,
+    });
+  }
+
+  let extension: Extension;
+  try {
+    extension = (factory as ExtensionFactory)(config);
+  } catch (err) {
+    throw EXTENSION_VALIDATION_ERROR.create({
+      detail: `Extension factory at "${path}" threw during invocation: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+      cause: err,
+    });
+  }
+
+  return { extension, source, origin: path };
+}

package/src/src/extensions/index.ts

@@ -6,6 +6,19 @@
  * helpers consumers need to load, validate, and orchestrate extensions.
  *
  * @module extensions
+ * @example
+ * ```ts
+ * import { orchestrateExtensions } from "veryfront/extensions";
+ *
+ * const loader = await orchestrateExtensions({
+ *   projectDir: Deno.cwd(),
+ *   config,
+ *   logger,
+ * });
+ *
+ * // Later, on shutdown:
+ * await loader.teardownAll();
+ * ```
  */
 
 // Core types
@@ -40,6 +53,13 @@ export {
 // Loader
 export { ExtensionLoader } from "./loader.js";
 
+// Factory loader (dynamic-import of an extension factory)
+export { loadExtensionFactory } from "./factory-loader.js";
+
+// Orchestrator (discover → load → merge → setup)
+export type { OrchestrateOptions } from "./orchestrate.js";
+export { orchestrateExtensions } from "./orchestrate.js";
+
 // Validation
 export type { ConflictInfo } from "./validation.js";
 export { detectConflicts, validateExtension } from "./validation.js";

package/src/src/extensions/orchestrate.ts

@@ -0,0 +1,184 @@
+/**
+ * Extension orchestration pipeline.
+ *
+ * Discovers, loads, merges, sorts, and runs setup for every extension
+ * contributed by the four sources (config, package, project, local-file).
+ * Invoked once by `bootstrap()` after config resolution.
+ *
+ * @module extensions/orchestrate
+ */
+
+import { basename, dirname } from "../../deps/jsr.io/@std/path/1.1.4/mod.js";
+import * as defaultDiscovery from "./discovery.js";
+import { loadExtensionFactory as defaultLoadFactory } from "./factory-loader.js";
+import { ExtensionLoader } from "./loader.js";
+import type {
+  Extension,
+  ExtensionConfigEntry,
+  ExtensionLogger,
+  ExtensionSource,
+  ResolvedExtension,
+} from "./types.js";
+
+/**
+ * Options for `orchestrateExtensions`.
+ *
+ * The `discovery` and `loadFactory` fields are test seams — they are not
+ * part of the stable public API and default to the real implementations.
+ */
+export interface OrchestrateOptions {
+  projectDir: string;
+  config: { extensions?: ExtensionConfigEntry[] };
+  logger: ExtensionLogger;
+  /** @internal Override discovery functions in tests. */
+  discovery?: {
+    discoverPackageExtensions: typeof defaultDiscovery.discoverPackageExtensions;
+    discoverProjectExtensions: typeof defaultDiscovery.discoverProjectExtensions;
+    discoverLocalExtensions: typeof defaultDiscovery.discoverLocalExtensions;
+    mergeExtensions: typeof defaultDiscovery.mergeExtensions;
+  };
+  /** @internal Override factory loading in tests. */
+  loadFactory?: typeof defaultLoadFactory;
+}
+
+function isDisableDirective(
+  entry: ExtensionConfigEntry,
+): entry is { name: string; enabled: false } {
+  return (
+    typeof entry === "object" &&
+    entry !== null &&
+    "enabled" in entry &&
+    (entry as { enabled: unknown }).enabled === false
+  );
+}
+
+/**
+ * Extract the extension name from a project-extension path.
+ *
+ * Project extensions live under `<baseDir>/extensions/<name>/...`. Discovery
+ * emits either `<baseDir>/extensions/<name>/src/index.ts` or
+ * `<baseDir>/extensions/<name>/index.ts`. This walks parent directories until
+ * it finds the ancestor whose parent is `extensions/`.
+ */
+function projectExtensionNameFromPath(path: string): string | undefined {
+  let current = dirname(path);
+  // Safety limit in case of a malformed path that never reaches a root.
+  for (let i = 0; i < 8; i++) {
+    const parent = dirname(current);
+    if (basename(parent) === "extensions") {
+      return basename(current);
+    }
+    if (parent === current) return undefined;
+    current = parent;
+  }
+  return undefined;
+}
+
+/**
+ * Run the full extension pipeline against a resolved project config.
+ *
+ * Pipeline:
+ *   1. Split `config.extensions` into resolved entries and disable directives.
+ *   2. Discover extensions from package, project, and local sources.
+ *   3. Skip loading factories for package- and project-source extensions whose
+ *      names appear in the disable set (local-file names are not reliable
+ *      pre-load and are filtered after `mergeExtensions`).
+ *   4. Dynamic-import factories for every remaining discovered path.
+ *   5. Merge sources honoring priority `config > package > project > local-file`.
+ *   6. Construct an `ExtensionLoader` and run `setupAll`.
+ *
+ * On factory error during `setup()`, `ExtensionLoader.setupAll` performs
+ * partial rollback internally. The error is re-thrown unchanged so callers
+ * can surface the extension name to the user.
+ */
+export async function orchestrateExtensions(
+  options: OrchestrateOptions,
+): Promise<ExtensionLoader> {
+  const { projectDir, config, logger } = options;
+  const disc = options.discovery ?? defaultDiscovery;
+  const loadFactory = options.loadFactory ?? defaultLoadFactory;
+
+  const configEntries = Array.isArray(config.extensions) ? config.extensions : [];
+  const disables: Array<{ name: string; enabled: false }> = [];
+  const configResolved: ResolvedExtension[] = [];
+
+  for (const entry of configEntries) {
+    if (isDisableDirective(entry)) {
+      disables.push(entry);
+    } else {
+      configResolved.push({
+        extension: entry as Extension,
+        source: "config",
+        origin: "veryfront.config",
+      });
+    }
+  }
+
+  // Build the disabled-names set early so we can skip dynamic imports for
+  // extensions the user has explicitly turned off. A factory whose module
+  // fails to import or invoke would otherwise take down bootstrap even
+  // though the user asked for it to be disabled.
+  const disabledNames = new Set(disables.map((d) => d.name));
+
+  const [packageHits, projectPaths, localPaths] = await Promise.all([
+    disc.discoverPackageExtensions(projectDir),
+    disc.discoverProjectExtensions(projectDir),
+    disc.discoverLocalExtensions(projectDir),
+  ]);
+
+  // Package hits carry the package name directly — filter before loading.
+  const enabledPackageNames = packageHits
+    .map((hit) => hit.packageName)
+    .filter((name) => !disabledNames.has(name));
+
+  // Project paths have the shape `<projectDir>/extensions/<name>/src/index.ts`
+  // (or `<projectDir>/extensions/<name>/index.ts`). `mergeExtensions` is the
+  // safety net for any path whose name cannot be derived.
+  const enabledProjectPaths = projectPaths.filter((path) => {
+    const name = projectExtensionNameFromPath(path);
+    return name === undefined || !disabledNames.has(name);
+  });
+
+  // Local-file paths cannot be reliably filtered pre-load: the filename
+  // (`foo.extension.ts`) is not guaranteed to match the extension name
+  // declared by the factory. `mergeExtensions` applies the post-hoc filter.
+  const packageResolved = await loadAllFactories(
+    enabledPackageNames,
+    "package",
+    loadFactory,
+  );
+  const projectResolved = await loadAllFactories(
+    enabledProjectPaths,
+    "project",
+    loadFactory,
+  );
+  const localResolved = await loadAllFactories(
+    localPaths,
+    "local-file",
+    loadFactory,
+  );
+
+  const merged = disc.mergeExtensions(
+    configResolved,
+    packageResolved,
+    projectResolved,
+    localResolved,
+    disables,
+  );
+
+  const loader = new ExtensionLoader(logger);
+  await loader.setupAll(merged, config as Record<string, unknown>);
+  return loader;
+}
+
+async function loadAllFactories(
+  paths: string[],
+  source: ExtensionSource,
+  loadFactory: typeof defaultLoadFactory,
+): Promise<ResolvedExtension[]> {
+  const resolved: ResolvedExtension[] = [];
+  for (const path of paths) {
+    resolved.push(await loadFactory(path, source));
+  }
+  return resolved;
+}

package/src/src/html/styles-builder/plugin-loader.ts

@@ -21,9 +21,34 @@ import {
   VeryfrontError,
 } from "../../errors/index.js";
 import { getTailwindPluginBundleUrl } from "../../build/binary-plugin-includes.js";
+import {
+  bareName,
+  PACKAGE_SPEC_RE,
+  TAILWIND_PLUGIN_ALLOWLIST,
+} from "./tailwind-plugin-allowlist.js";
 
 const logger = serverLogger.component("tailwind");
 
+/**
+ * Enforce the Tailwind plugin allowlist (VULN-FS-1).
+ *
+ * Called at the top of every entry point that can load third-party plugin
+ * code. Rejects anything that is not a syntactically valid npm package
+ * specifier, and anything whose bare name is not on the allowlist.
+ */
+function assertPluginAllowed(spec: string): void {
+  if (!PACKAGE_SPEC_RE.test(spec)) {
+    throw new Error(`Invalid Tailwind plugin specifier: ${spec}`);
+  }
+  const name = bareName(spec);
+  if (!TAILWIND_PLUGIN_ALLOWLIST.has(name)) {
+    throw new Error(
+      `Package "${name}" is not on the Tailwind plugin allowlist. ` +
+        `See src/html/styles-builder/tailwind-plugin-allowlist.ts.`,
+    );
+  }
+}
+
 // Provide localStorage shim for plugins that use util-deprecate (which checks localStorage)
 // This prevents "LocalStorage is not supported in this context" errors in Deno.
 try {
@@ -109,6 +134,8 @@ async function importBundledModule(code: string): Promise<unknown> {
  * dynamic imports from URLs. Fetches bundled code, rewrites imports, loads via temp file.
  */
 export async function loadModuleFromEsmSh(packageName: string): Promise<unknown> {
+  assertPluginAllowed(packageName);
+
   const stubUrl = getTailwindPluginBundleUrl(packageName);
   logger.debug("Fetching esm.sh stub", { url: stubUrl });
 
@@ -173,6 +200,11 @@ export async function loadPlugin(
   pluginCache: Map<string, unknown>,
   pluginErrors: Map<string, Error>,
 ): Promise<unknown> {
+  // Enforce the allowlist before consulting any caches so a disallowed id can
+  // never be served from a pre-seeded or stale cache entry — defence-in-depth
+  // against future changes that might pre-populate these maps.
+  assertPluginAllowed(id);
+
   const cachedError = pluginErrors.get(id);
   if (cachedError) throw cachedError;
 

package/src/src/html/styles-builder/tailwind-plugin-allowlist.ts

@@ -0,0 +1,51 @@
+/**
+ * Allowlist of Tailwind CSS plugin package names that may be dynamically loaded
+ * via `loadPlugin` / `loadModuleFromEsmSh`.
+ *
+ * Tailwind v4 stylesheets can request plugins through the `@plugin "..."`
+ * directive. Without restriction, this turns arbitrary project CSS into a
+ * remote-code-execution vector because the loader fetches and imports code
+ * from https://esm.sh. Only the packages listed here may be loaded.
+ *
+ * @module html/styles-builder/tailwind-plugin-allowlist
+ */
+
+export const TAILWIND_PLUGIN_ALLOWLIST: ReadonlySet<string> = new Set([
+  // Bundled into the compiled binary (see src/build/binary-plugin-includes.ts).
+  // Must stay in sync with BINARY_TAILWIND_PLUGIN_PACKAGES — an invariant
+  // enforced by tailwind-plugin-allowlist.test.ts.
+  "@tailwindcss/typography",
+  "@tailwindcss/forms",
+  "tailwindcss-animate",
+  "tailwind-scrollbar-hide",
+  "daisyui",
+  // Allowlisted but NOT bundled: loaded from esm.sh on first use. Adding an
+  // entry here is arbitrary-code-exec surface; review each one explicitly.
+  "@tailwindcss/aspect-ratio",
+  "@tailwindcss/container-queries",
+]);
+
+/**
+ * Matches npm package specifiers, optionally scoped and optionally suffixed
+ * with an `@version` range. Deliberately restrictive: ASCII only, no path
+ * separators, no whitespace, no control characters.
+ */
+export const PACKAGE_SPEC_RE = /^(?:@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*(?:@[\w.+-]+)?$/i;
+
+/**
+ * Return the bare package name (without any `@version` suffix) for a spec.
+ *
+ * Examples:
+ *   bareName("pkg")            -> "pkg"
+ *   bareName("pkg@1.0.0")      -> "pkg"
+ *   bareName("@scope/pkg")     -> "@scope/pkg"
+ *   bareName("@scope/pkg@1.0") -> "@scope/pkg"
+ */
+export function bareName(spec: string): string {
+  if (spec.startsWith("@")) {
+    const idx = spec.indexOf("@", 1);
+    return idx === -1 ? spec : spec.slice(0, idx);
+  }
+  const idx = spec.indexOf("@");
+  return idx === -1 ? spec : spec.slice(0, idx);
+}

package/src/src/modules/react-loader/ssr-module-loader/loader-helpers.ts

@@ -0,0 +1,37 @@
+import { createError, toError } from "../../../errors/veryfront-error.js";
+
+const MISSING_HTTP_BUNDLE_PATTERN = /veryfront-http-bundle\/http-([a-f0-9]+)\.mjs/;
+
+export type TransformCapacityErrorMode = "plain" | "build";
+
+export type ImportErrorClassification =
+  | { type: "http-bundle-missing"; hash: string; message: string }
+  | { type: "module-not-found"; message: string }
+  | { type: "unknown"; message: string };
+
+export function classifyImportError(importError: unknown): ImportErrorClassification {
+  const message = importError instanceof Error ? importError.message : String(importError);
+  const bundleMatch = message.match(MISSING_HTTP_BUNDLE_PATTERN);
+  if (bundleMatch?.[1]) {
+    return { type: "http-bundle-missing", hash: bundleMatch[1], message };
+  }
+  if (message.includes("Cannot find module") || message.includes("Module not found")) {
+    return { type: "module-not-found", message };
+  }
+  return { type: "unknown", message };
+}
+
+export function createTransformCapacityError(
+  mode: TransformCapacityErrorMode,
+  message: string,
+  filePath: string,
+): Error {
+  if (mode === "plain") return new Error(message);
+  return toError(
+    createError({
+      type: "build",
+      message,
+      context: { file: filePath, phase: "transform" },
+    }),
+  );
+}

package/src/src/modules/react-loader/ssr-module-loader/loader.ts

@@ -22,6 +22,11 @@ import { rendererLogger } from "../../../utils/index.js";
 import { withSpan } from "../../../observability/tracing/otlp-setup.js";
 import { SpanNames } from "../../../observability/tracing/span-names.js";
 import { extractComponent } from "../extract-component.js";
+import {
+  classifyImportError,
+  createTransformCapacityError,
+  type TransformCapacityErrorMode,
+} from "./loader-helpers.js";
 import {
   getMaxConcurrentTransforms,
   IN_PROGRESS_WAIT_TIMEOUT_MS,
@@ -58,15 +63,6 @@ import { ensureMdxModuleDependencies } from "../../../transforms/mdx/esm-module-
 
 const logger = rendererLogger.component("ssr-module-loader");
 
-const MISSING_HTTP_BUNDLE_PATTERN = /veryfront-http-bundle\/http-([a-f0-9]+)\.mjs/;
-
-type TransformCapacityErrorMode = "plain" | "build";
-
-type ImportErrorClassification =
-  | { type: "http-bundle-missing"; hash: string; message: string }
-  | { type: "module-not-found"; message: string }
-  | { type: "unknown"; message: string };
-
 /**
  * SSR Module Loader with Redis Support.
  *
@@ -89,33 +85,6 @@ export class SSRModuleLoader {
     );
   }
 
-  private classifyImportError(importError: unknown): ImportErrorClassification {
-    const message = importError instanceof Error ? importError.message : String(importError);
-    const bundleMatch = message.match(MISSING_HTTP_BUNDLE_PATTERN);
-    if (bundleMatch?.[1]) {
-      return { type: "http-bundle-missing", hash: bundleMatch[1], message };
-    }
-    if (message.includes("Cannot find module") || message.includes("Module not found")) {
-      return { type: "module-not-found", message };
-    }
-    return { type: "unknown", message };
-  }
-
-  private createTransformCapacityError(
-    mode: TransformCapacityErrorMode,
-    message: string,
-    filePath: string,
-  ): Error {
-    if (mode === "plain") return new Error(message);
-    return toError(
-      createError({
-        type: "build",
-        message,
-        context: { file: filePath, phase: "transform" },
-      }),
-    );
-  }
-
   private async withTransformCapacity<T>(
     filePath: string,
     mode: TransformCapacityErrorMode,
@@ -127,7 +96,7 @@ export class SSRModuleLoader {
     let semaphoreAcquired = false;
 
     if (!await tryAcquireTransformSlot(projectId, TRANSFORM_ACQUIRE_TIMEOUT_MS)) {
-      throw this.createTransformCapacityError(
+      throw createTransformCapacityError(
         mode,
         `Project ${projectId} at transform capacity. Consider reducing page complexity or request rate.`,
         filePath,
@@ -138,7 +107,7 @@ export class SSRModuleLoader {
       if (semaphore) {
         semaphoreAcquired = await semaphore.tryAcquire(TRANSFORM_ACQUIRE_TIMEOUT_MS);
         if (!semaphoreAcquired) {
-          throw this.createTransformCapacityError(
+          throw createTransformCapacityError(
             mode,
             `Transform capacity exceeded (${semaphore.waiting} waiting). Service is overloaded.`,
             filePath,
@@ -189,7 +158,7 @@ export class SSRModuleLoader {
         { "ssr.file": fileName },
       )) as Record<string, unknown>;
     } catch (importError) {
-      const classifiedError = this.classifyImportError(importError);
+      const classifiedError = classifyImportError(importError);
 
       if (classifiedError.type === "http-bundle-missing") {
         const hash = classifiedError.hash;

package/src/src/platform/adapters/fs/veryfront/adapter-helpers.ts

@@ -0,0 +1,43 @@
+import type { VeryfrontAPIConfig } from "../../veryfront-api-client/types.js";
+import type { FileCacheOptions } from "../cache/types.js";
+import type { ContentSource, FSAdapterConfig } from "./types.js";
+
+export const DEFAULT_MAX_RETRIES = 3;
+export const DEFAULT_INITIAL_RETRY_DELAY_MS = 1_000;
+export const DEFAULT_MAX_RETRY_DELAY_MS = 10_000;
+export const DEFAULT_CACHE_TTL_MS = 60_000;
+export const DEFAULT_CACHE_MAX_ENTRIES = 1_000;
+export const DEFAULT_CACHE_MAX_MEMORY_BYTES = 100 * 1024 * 1024;
+
+type VeryfrontConfigOverrides = NonNullable<FSAdapterConfig["veryfront"]>;
+type RetryOverrides = VeryfrontConfigOverrides["retry"];
+type CacheOverrides = VeryfrontConfigOverrides["cache"];
+
+export function buildRetryConfig(
+  retry?: RetryOverrides,
+): NonNullable<VeryfrontAPIConfig["retry"]> {
+  return {
+    maxRetries: DEFAULT_MAX_RETRIES,
+    initialDelay: DEFAULT_INITIAL_RETRY_DELAY_MS,
+    maxDelay: DEFAULT_MAX_RETRY_DELAY_MS,
+    ...retry,
+  };
+}
+
+export function buildFileCacheOptions(
+  cache?: CacheOverrides,
+): FileCacheOptions {
+  return {
+    enabled: true,
+    ttl: DEFAULT_CACHE_TTL_MS,
+    maxSize: DEFAULT_CACHE_MAX_ENTRIES,
+    maxMemory: DEFAULT_CACHE_MAX_MEMORY_BYTES,
+    ...cache,
+  };
+}
+
+export function shouldBackgroundPregenerateStyles(
+  contentContext: { sourceType: ContentSource["type"] } | null,
+): boolean {
+  return contentContext?.sourceType !== "branch";
+}

package/src/src/platform/adapters/fs/veryfront/adapter.ts

@@ -13,7 +13,6 @@ import type { FileInfo, ResolveFileOptions } from "../../base.js";
 import { VeryfrontApiClient } from "../../veryfront-api-client/index.js";
 import type { Project } from "../../veryfront-api-client/index.js";
 import { FileCache } from "../cache/file-cache.js";
-import type { FileCacheOptions } from "../cache/types.js";
 import { PathNormalizer } from "./path-normalizer.js";
 import { ReadOperations } from "./read-operations.js";
 import { DirectoryOperations } from "./directory-operations.js";
@@ -28,16 +27,14 @@ import {
   summarizeFileList,
   toClientContext,
 } from "./adapter-content-context.js";
+import {
+  buildFileCacheOptions,
+  buildRetryConfig,
+  shouldBackgroundPregenerateStyles,
+} from "./adapter-helpers.js";
 
 const logger = baseLogger.component("veryfront-fs-adapter");
 
-const DEFAULT_MAX_RETRIES = 3;
-const DEFAULT_INITIAL_RETRY_DELAY_MS = 1_000;
-const DEFAULT_MAX_RETRY_DELAY_MS = 10_000;
-const DEFAULT_CACHE_TTL_MS = 60_000;
-const DEFAULT_CACHE_MAX_ENTRIES = 1_000;
-const DEFAULT_CACHE_MAX_MEMORY_BYTES = 100 * 1024 * 1024;
-
 export class VeryfrontFSAdapter implements FSAdapter {
   private client: VeryfrontApiClient;
   private cache: FileCache;
@@ -126,12 +123,7 @@ export class VeryfrontFSAdapter implements FSAdapter {
     this.contentSource = vf.contentSource ?? { type: "branch", branch: "main" };
     this.proxyMode = vf.proxyMode ?? false;
 
-    const retryConfig = {
-      maxRetries: DEFAULT_MAX_RETRIES,
-      initialDelay: DEFAULT_INITIAL_RETRY_DELAY_MS,
-      maxDelay: DEFAULT_MAX_RETRY_DELAY_MS,
-      ...vf.retry,
-    };
+    const retryConfig = buildRetryConfig(vf.retry);
 
     this.client = new VeryfrontApiClient({
       apiBaseUrl: this.apiBaseUrl,
@@ -142,13 +134,7 @@ export class VeryfrontFSAdapter implements FSAdapter {
       retry: retryConfig,
     });
 
-    const cacheConfig: FileCacheOptions = {
-      enabled: true,
-      ttl: DEFAULT_CACHE_TTL_MS,
-      maxSize: DEFAULT_CACHE_MAX_ENTRIES,
-      maxMemory: DEFAULT_CACHE_MAX_MEMORY_BYTES,
-      ...vf.cache,
-    };
+    const cacheConfig = buildFileCacheOptions(vf.cache);
 
     this.cache = new FileCache(cacheConfig);
     this.normalizer = new PathNormalizer(config.projectDir);
@@ -396,7 +382,7 @@ export class VeryfrontFSAdapter implements FSAdapter {
     // Branch previews should recover the last registered stylesheet artifact on
     // cold starts before rebuilding CSS locally. Live edit pokes still
     // pregenerate through the WebSocket path after branch content changes.
-    return this.contentContext?.sourceType !== "branch";
+    return shouldBackgroundPregenerateStyles(this.contentContext);
   }
 
   private scheduleFileListWarmup(reason: string, cacheKey?: string): void {

package/src/src/platform/adapters/fs/veryfront/read-operations-helpers.ts

@@ -80,6 +80,10 @@ export function getResolvedCacheKey(
   return `${cacheKeyPrefix}:${normalizedResolvedPath}`;
 }
 
+export function buildContentPreview(content: string, max = 80): string {
+  return content.length > max ? `${content.slice(0, max)}...` : content;
+}
+
 export function buildExtensionCandidatePaths(basePath: string): string[] {
   return READ_OPERATION_EXTENSION_PRIORITY.map((ext) => `${basePath}${ext}`);
 }