astro 7.1.6 → 7.2.0

package/dist/core/app/entrypoints/index.js

@@ -12,15 +12,29 @@ import {
   serializeRouteInfo
 } from "../manifest.js";
 import { AppPipeline } from "../pipeline.js";
+import {
+  beginContentEntryCollection,
+  endContentEntryCollection
+} from "../../build/incremental-content-collector.js";
+import {
+  beginImageCollection,
+  endImageCollection,
+  recordStaticImage
+} from "../../build/incremental-image-collector.js";
 export {
   App,
   AppPipeline,
   BaseApp,
+  beginContentEntryCollection,
+  beginImageCollection,
   createConsoleLogger,
   deserializeManifest,
   deserializeRouteData,
   deserializeRouteInfo,
+  endContentEntryCollection,
+  endImageCollection,
   fromRoutingStrategy,
+  recordStaticImage,
   serializeRouteData,
   serializeRouteInfo,
   toRoutingStrategy

package/dist/core/build/config-hash/index.d.ts

@@ -0,0 +1,8 @@
+import type { AstroConfig } from '../../../types/public/config.js';
+export { getConfigHashInput } from './input.js';
+/**
+ * Produce a sha256 over the output-affecting subset of the resolved config (see
+ * {@link getConfigHashInput}). A mismatch invalidates the whole incremental
+ * build cache.
+ */
+export declare function computeConfigHash(config: AstroConfig): Promise<string>;

package/dist/core/build/config-hash/index.js

@@ -0,0 +1,23 @@
+import { encodeHexLowerCase } from "@oslojs/encoding";
+import { getConfigHashInput } from "./input.js";
+import { getConfigHashInput as getConfigHashInput2 } from "./input.js";
+function stableStringify(value) {
+  return JSON.stringify(value, (_key, val) => {
+    if (val && typeof val === "object" && !Array.isArray(val)) {
+      return Object.keys(val).sort().reduce((acc, key) => {
+        acc[key] = val[key];
+        return acc;
+      }, {});
+    }
+    return val;
+  });
+}
+async function computeConfigHash(config) {
+  const input = stableStringify(getConfigHashInput(config));
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(input));
+  return encodeHexLowerCase(new Uint8Array(digest));
+}
+export {
+  computeConfigHash,
+  getConfigHashInput2 as getConfigHashInput
+};

package/dist/core/build/config-hash/input.d.ts

@@ -0,0 +1,199 @@
+import type { AstroConfig } from '../../../types/public/config.js';
+/**
+ * Projection of {@link AstroConfig} limited to values that can change the bytes
+ * or paths of a prerendered page. A change to any of these must invalidate the
+ * incremental build cache: the per-route dependency hash only sees module
+ * *source*, so it misses config baked into compiled output by the compiler
+ * (`compressHTML`, `site`, `scopedStyleStrategy`), inlined via Vite `define`
+ * (`base`, `build.assetsPrefix`), or serialized into virtual modules (`image`,
+ * `env.schema`, `i18n`).
+ *
+ * Only serializable values are included. Function-valued config (integrations,
+ * vite/remark/rehype plugins, image services) is omitted because it cannot be
+ * serialized. `outDir`/`publicDir` are omitted too, since they move where files
+ * are written without changing a page's bytes.
+ *
+ * The whole `vite` config cannot be hashed: it carries plugins and other
+ * function-valued, per-run state that churns between builds and would sink the
+ * cache hit rate. Instead a curated allowlist of serializable Vite options that
+ * change emitted bytes or asset paths is included (e.g. `build.assetsInlineLimit`
+ * flips an asset between an inlined data URI and a separate hashed file). This
+ * allowlist is best-effort, so an obscure output-affecting Vite option outside
+ * it will not invalidate the cache; `--force` is the escape hatch.
+ *
+ * The set of fields is asserted against the full config schema in
+ * `test/units/build/config-hash.test.ts`, which fails when a new top-level
+ * config key appears so it gets classified here or explicitly excluded.
+ */
+export declare function getConfigHashInput(config: AstroConfig): {
+    site: string | undefined;
+    base: string;
+    trailingSlash: "never" | "ignore" | "always";
+    output: "server" | "static";
+    compressHTML: boolean | "jsx";
+    scopedStyleStrategy: "where" | "class" | "attribute";
+    build: {
+        format: "file" | "directory" | "preserve";
+        assets: string;
+        assetsPrefix: string | ({
+            fallback: string;
+        } & Record<string, string>) | undefined;
+        inlineStylesheets: "never" | "always" | "auto";
+        redirects: boolean;
+    };
+    redirects: Record<string, string | {
+        status: 301 | 302 | 303 | 307 | 308 | 300 | 304;
+        destination: string;
+    }>;
+    i18n: {
+        defaultLocale: string;
+        locales: (string | {
+            path: string;
+            codes: [string, ...string[]];
+        })[];
+        routing: "manual" | {
+            prefixDefaultLocale: boolean;
+            redirectToDefaultLocale: boolean;
+            fallbackType: "redirect" | "rewrite";
+        };
+        domains?: Record<string, string> | undefined;
+        fallback?: Record<string, string> | undefined;
+    } | undefined;
+    image: {
+        endpoint: {
+            route: string;
+            entrypoint?: string | undefined;
+        };
+        service: {
+            entrypoint: string;
+            config: Record<string, any>;
+        };
+        dangerouslyProcessSVG: boolean;
+        domains: string[];
+        remotePatterns: {
+            protocol?: string | undefined;
+            hostname?: string | undefined;
+            port?: string | undefined;
+            pathname?: string | undefined;
+        }[];
+        responsiveStyles: boolean;
+        layout?: "fixed" | "constrained" | "full-width" | "none" | undefined;
+        objectFit?: string | undefined;
+        objectPosition?: string | undefined;
+        breakpoints?: number[] | undefined;
+    };
+    markdown: {
+        syntaxHighlight: false | "shiki" | "prism" | {
+            type: "shiki" | "prism";
+            excludeLangs?: string[] | undefined;
+        };
+        shikiConfig: {
+            langs: (import("shiki").LanguageRegistration & import("../../config/schemas/base.js").ComplexifyUnionObj)[];
+            langAlias: Record<string, string>;
+            theme: "andromeeda" | "aurora-x" | "ayu-dark" | "ayu-light" | "ayu-mirage" | "catppuccin-frappe" | "catppuccin-latte" | "catppuccin-macchiato" | "catppuccin-mocha" | "dark-plus" | "dracula" | "dracula-soft" | "everforest-dark" | "everforest-light" | "github-dark" | "github-dark-default" | "github-dark-dimmed" | "github-dark-high-contrast" | "github-light" | "github-light-default" | "github-light-high-contrast" | "gruvbox-dark-hard" | "gruvbox-dark-medium" | "gruvbox-dark-soft" | "gruvbox-light-hard" | "gruvbox-light-medium" | "gruvbox-light-soft" | "horizon" | "horizon-bright" | "houston" | "kanagawa-dragon" | "kanagawa-lotus" | "kanagawa-wave" | "laserwave" | "light-plus" | "material-theme" | "material-theme-darker" | "material-theme-lighter" | "material-theme-ocean" | "material-theme-palenight" | "min-dark" | "min-light" | "monokai" | "night-owl" | "night-owl-light" | "nord" | "one-dark-pro" | "one-light" | "plastic" | "poimandres" | "red" | "rose-pine" | "rose-pine-dawn" | "rose-pine-moon" | "slack-dark" | "slack-ochin" | "snazzy-light" | "solarized-dark" | "solarized-light" | "synthwave-84" | "tokyo-night" | "vesper" | "vitesse-black" | "vitesse-dark" | "vitesse-light" | (NonNullable<(import("shiki").BundledTheme | "css-variables") | import("shiki").ThemeRegistration | import("shiki").ThemeRegistrationRaw | undefined> & import("../../config/schemas/base.js").ComplexifyUnionObj);
+            themes: Record<string, "andromeeda" | "aurora-x" | "ayu-dark" | "ayu-light" | "ayu-mirage" | "catppuccin-frappe" | "catppuccin-latte" | "catppuccin-macchiato" | "catppuccin-mocha" | "dark-plus" | "dracula" | "dracula-soft" | "everforest-dark" | "everforest-light" | "github-dark" | "github-dark-default" | "github-dark-dimmed" | "github-dark-high-contrast" | "github-light" | "github-light-default" | "github-light-high-contrast" | "gruvbox-dark-hard" | "gruvbox-dark-medium" | "gruvbox-dark-soft" | "gruvbox-light-hard" | "gruvbox-light-medium" | "gruvbox-light-soft" | "horizon" | "horizon-bright" | "houston" | "kanagawa-dragon" | "kanagawa-lotus" | "kanagawa-wave" | "laserwave" | "light-plus" | "material-theme" | "material-theme-darker" | "material-theme-lighter" | "material-theme-ocean" | "material-theme-palenight" | "min-dark" | "min-light" | "monokai" | "night-owl" | "night-owl-light" | "nord" | "one-dark-pro" | "one-light" | "plastic" | "poimandres" | "red" | "rose-pine" | "rose-pine-dawn" | "rose-pine-moon" | "slack-dark" | "slack-ochin" | "snazzy-light" | "solarized-dark" | "solarized-light" | "synthwave-84" | "tokyo-night" | "vesper" | "vitesse-black" | "vitesse-dark" | "vitesse-light" | (NonNullable<(import("shiki").BundledTheme | "css-variables") | import("shiki").ThemeRegistration | import("shiki").ThemeRegistrationRaw | undefined> & import("../../config/schemas/base.js").ComplexifyUnionObj)>;
+            wrap: boolean | null;
+            transformers: (import("shiki").ShikiTransformer & import("../../config/schemas/base.js").ComplexifyUnionObj)[];
+            defaultColor?: string | false | undefined;
+        };
+        remarkPlugins: (string | [string, any] | (import("@astrojs/markdown-remark").RemarkPlugin & import("../../config/schemas/base.js").ComplexifyUnionObj) | [import("@astrojs/markdown-remark").RemarkPlugin & import("../../config/schemas/base.js").ComplexifyUnionObj, any])[];
+        rehypePlugins: (string | [string, any] | (import("@astrojs/markdown-remark").RehypePlugin & import("../../config/schemas/base.js").ComplexifyUnionObj) | [import("@astrojs/markdown-remark").RehypePlugin & import("../../config/schemas/base.js").ComplexifyUnionObj, any])[];
+        remarkRehype: import("../../config/schemas/base.js").RemarkRehype;
+        processor: {
+            name: string;
+            options: object;
+            createRenderer: (shared: import("@astrojs/markdown-remark").AstroMarkdownOptions) => Promise<import("@astrojs/markdown-remark").MarkdownRenderer>;
+            createMdxRenderer?: ((shared: import("@astrojs/markdown-remark").AstroMarkdownOptions, mdx: import("@astrojs/internal-helpers/markdown").MdxRendererOptions) => Promise<import("@astrojs/internal-helpers/markdown").MdxRenderer>) | undefined;
+        };
+        gfm?: boolean | undefined;
+        smartypants?: false | import("../../config/schemas/base.js").Smartypants | undefined;
+    };
+    env: {
+        schema: Record<string, ({
+            context: "client";
+            access: "public";
+        } | {
+            context: "server";
+            access: "public";
+        } | {
+            context: "server";
+            access: "secret";
+        }) & ({
+            type: "enum";
+            values: string[];
+            optional?: boolean | undefined;
+            default?: string | undefined;
+        } | {
+            type: "string";
+            optional?: boolean | undefined;
+            default?: string | undefined;
+            max?: number | undefined;
+            min?: number | undefined;
+            length?: number | undefined;
+            url?: boolean | undefined;
+            includes?: string | undefined;
+            startsWith?: string | undefined;
+            endsWith?: string | undefined;
+        } | {
+            type: "number";
+            optional?: boolean | undefined;
+            default?: number | undefined;
+            gt?: number | undefined;
+            min?: number | undefined;
+            lt?: number | undefined;
+            max?: number | undefined;
+            int?: boolean | undefined;
+        } | {
+            type: "boolean";
+            optional?: boolean | undefined;
+            default?: boolean | undefined;
+        })>;
+    };
+    security: {
+        csp: boolean | {
+            algorithm: "SHA-256" | "SHA-384" | "SHA-512";
+            directives?: (`base-uri${string}` | `child-src${string}` | `connect-src${string}` | `default-src${string}` | `fenced-frame-src${string}` | `font-src${string}` | `form-action${string}` | `frame-ancestors${string}` | `frame-src${string}` | `img-src${string}` | `manifest-src${string}` | `media-src${string}` | `object-src${string}` | `referrer${string}` | `report-to${string}` | `report-uri${string}` | `require-trusted-types-for${string}` | `sandbox${string}` | `trusted-types${string}` | `upgrade-insecure-requests${string}` | `worker-src${string}`)[] | undefined;
+            styleDirective?: {
+                resources?: (string | {
+                    resource: string;
+                    kind: "default" | "attribute" | "element";
+                })[] | undefined;
+                hashes?: (`sha256-${string}` | `sha384-${string}` | `sha512-${string}` | {
+                    hash: `sha256-${string}` | `sha384-${string}` | `sha512-${string}`;
+                    kind: "default" | "attribute" | "element";
+                })[] | undefined;
+            } | undefined;
+            scriptDirective?: {
+                resources?: (string | {
+                    resource: string;
+                    kind: "default" | "attribute" | "element";
+                })[] | undefined;
+                hashes?: (`sha256-${string}` | `sha384-${string}` | `sha512-${string}` | {
+                    hash: `sha256-${string}` | `sha384-${string}` | `sha512-${string}`;
+                    kind: "default" | "attribute" | "element";
+                })[] | undefined;
+                strictDynamic?: boolean | undefined;
+            } | undefined;
+        };
+    };
+    prefetch: boolean | {
+        prefetchAll?: boolean | undefined;
+        defaultStrategy?: "tap" | "hover" | "viewport" | "load" | undefined;
+    } | undefined;
+    vite: {
+        build: {
+            assetsInlineLimit: number | ((filePath: string, content: Buffer) => boolean | undefined) | undefined;
+            minify: boolean | "esbuild" | "oxc" | "terser" | undefined;
+            cssMinify: boolean | "esbuild" | "lightningcss" | undefined;
+            cssTarget: false | import("vite/types/internal/esbuildOptions.js").EsbuildTarget | undefined;
+            target: false | import("vite/types/internal/esbuildOptions.js").EsbuildTarget | undefined;
+        };
+        css: import("vite").CSSOptions | undefined;
+        json: import("vite").JsonOptions | undefined;
+        define: Record<string, any> | undefined;
+        oxc: false | import("vite").OxcOptions | undefined;
+    };
+    experimental: {
+        clientPrerender: boolean;
+    };
+};

package/dist/core/build/config-hash/input.js

@@ -0,0 +1,43 @@
+function getConfigHashInput(config) {
+  return {
+    site: config.site,
+    base: config.base,
+    trailingSlash: config.trailingSlash,
+    output: config.output,
+    compressHTML: config.compressHTML,
+    scopedStyleStrategy: config.scopedStyleStrategy,
+    build: {
+      format: config.build.format,
+      assets: config.build.assets,
+      assetsPrefix: config.build.assetsPrefix,
+      inlineStylesheets: config.build.inlineStylesheets,
+      redirects: config.build.redirects
+    },
+    redirects: config.redirects,
+    i18n: config.i18n,
+    image: config.image,
+    markdown: config.markdown,
+    env: { schema: config.env?.schema },
+    security: { csp: config.security?.csp },
+    prefetch: config.prefetch,
+    vite: {
+      build: {
+        assetsInlineLimit: config.vite.build?.assetsInlineLimit,
+        minify: config.vite.build?.minify,
+        cssMinify: config.vite.build?.cssMinify,
+        cssTarget: config.vite.build?.cssTarget,
+        target: config.vite.build?.target
+      },
+      css: config.vite.css,
+      json: config.vite.json,
+      define: config.vite.define,
+      oxc: config.vite.oxc
+    },
+    experimental: {
+      clientPrerender: config.experimental.clientPrerender
+    }
+  };
+}
+export {
+  getConfigHashInput
+};

package/dist/core/build/generate.d.ts

@@ -1,5 +1,5 @@
 import type { AstroLogger } from '../logger/core.js';
-import type { AstroPrerenderer, RouteToHeaders } from '../../types/public/index.js';
+import type { AstroPrerenderer, PrerenderResult, RouteToHeaders } from '../../types/public/index.js';
 import type { RouteData } from '../../types/public/internal.js';
 import { type BuildInternals } from './internal.js';
 import type { StaticBuildOptions } from './types.js';
@@ -13,6 +13,8 @@ export interface RenderPathResult {
     body: string | Uint8Array;
     outFile: URL;
     outFolder: URL;
+    /** Incremental-build metadata the prerenderer reported for this page, if any. */
+    metadata?: PrerenderResult['metadata'];
 }
 interface RenderToPathPayload {
     prerenderer: AstroPrerenderer;

package/dist/core/build/generate.js

@@ -1,12 +1,14 @@
 import nodeFs from "node:fs";
 import os from "node:os";
+import { fileURLToPath } from "node:url";
 import PLimit from "p-limit";
 import PQueue from "p-queue";
 import colors from "piccolore";
 import {
   generateImagesForPath,
   getStaticImageList,
-  prepareAssetsGenerationEnv
+  prepareAssetsGenerationEnv,
+  restoreStaticImages
 } from "../../assets/build/generate.js";
 import {
   appendForwardSlash,
@@ -18,6 +20,7 @@ import {
   trimSlashes
 } from "../../core/path.js";
 import { runHookBuildGenerated, toIntegrationResolvedRoute } from "../../integrations/hooks.js";
+import { hashCryptoKey } from "../encryption.js";
 import { AstroError, AstroErrorData } from "../errors/index.js";
 import { getRedirectLocationOrThrow } from "../redirects/index.js";
 import { createRequest } from "../request.js";
@@ -27,6 +30,14 @@ import { matchRoute } from "../routing/match.js";
 import { getOutputFilename } from "../output-filename.js";
 import { getOutFile, getOutFolder } from "./common.js";
 import { createDefaultPrerenderer } from "./default-prerenderer.js";
+import {
+  beginContentEntryCollection,
+  endContentEntryCollection
+} from "./incremental-content-collector.js";
+import { beginImageCollection, endImageCollection } from "./incremental-image-collector.js";
+import { IncrementalBuildCache } from "./incremental.js";
+import { computeConfigHash } from "./config-hash/index.js";
+import { computeLockfileHash } from "./lockfile/index.js";
 import { hasPrerenderedPages } from "./internal.js";
 import { getTimeStat, shouldAppendForwardSlash } from "./util.js";
 async function generatePages(options, internals, prerenderOutputDir) {
@@ -64,6 +75,29 @@ async function generatePages(options, internals, prerenderOutputDir) {
 ${colors.bgGreen(colors.black(` ${verb} static routes `))}`);
   const routeToHeaders = /* @__PURE__ */ new Map();
   let staticImageList = getStaticImageList();
+  let cache = null;
+  if (options.settings.config.experimental.incrementalBuild) {
+    if (options.settings.config.build.concurrency > 1) {
+      logger.warn(
+        "build",
+        "The incremental build cache is disabled because `build.concurrency` is greater than 1."
+      );
+    } else {
+      const [configHash, lockfileHash, keyDigest] = await Promise.all([
+        computeConfigHash(options.settings.config),
+        computeLockfileHash(fileURLToPath(options.settings.config.root)),
+        options.key.then(hashCryptoKey)
+      ]);
+      cache = IncrementalBuildCache.load(
+        options.settings,
+        configHash,
+        lockfileHash,
+        keyDigest,
+        internals.contentEntryRenderHashes ?? /* @__PURE__ */ new Map(),
+        options.force
+      );
+    }
+  }
   try {
     const pathsWithRoutes = await prerenderer.getStaticPaths();
     const hasI18nDomains = ssr && options.settings.config.i18n?.domains && Object.keys(options.settings.config.i18n.domains).length > 0;
@@ -119,14 +153,17 @@ ${colors.bgGreen(colors.black(` ${verb} static routes `))}`);
       for (const paths of generationPhases) {
         for (let i = 0; i < paths.length; i += BATCH_SIZE) {
           const promises = paths.slice(i, i + BATCH_SIZE).map(
-            ({ pathname, route }) => limit(
+            ({ pathname, route, cacheKey }) => limit(
               () => generatePathWithPrerenderer(
                 prerenderer,
                 pathname,
                 route,
                 options,
+                internals,
                 routeToHeaders,
-                logger
+                logger,
+                cache,
+                cacheKey
               )
             )
           );
@@ -135,14 +172,17 @@ ${colors.bgGreen(colors.black(` ${verb} static routes `))}`);
       }
     } else {
       for (const paths of generationPhases) {
-        for (const { pathname, route } of paths) {
+        for (const { pathname, route, cacheKey } of paths) {
           await generatePathWithPrerenderer(
             prerenderer,
             pathname,
             route,
             options,
+            internals,
             routeToHeaders,
-            logger
+            logger,
+            cache,
+            cacheKey
           );
         }
       }
@@ -159,6 +199,25 @@ ${colors.bgGreen(colors.black(` ${verb} static routes `))}`);
         }
       }
     }
+    if (cache) {
+      const orphans = cache.findOrphanedFiles();
+      let pruned = 0;
+      for (const orphanFile of orphans) {
+        try {
+          await cache.deleteOutputFile(options.settings, orphanFile);
+          pruned++;
+        } catch (err) {
+          logger.warn(
+            "build",
+            `Could not prune stale incremental cache file ${orphanFile}: ${err}`
+          );
+        }
+      }
+      if (pruned > 0) {
+        logger.info("build", `Pruned ${pruned} stale file(s) from the incremental cache.`);
+      }
+      cache.writeManifest(options.settings);
+    }
     staticImageList = getStaticImageList();
     if (prerenderer.collectStaticImages) {
       const adapterImages = await prerenderer.collectStaticImages();
@@ -206,6 +265,9 @@ ${colors.bgGreen(colors.black(` ${verb} static routes `))}`);
   });
 }
 const THRESHOLD_SLOW_RENDER_TIME_MS = 500;
+function normalizePrerenderResult(result) {
+  return result instanceof Response ? { response: result } : result;
+}
 async function renderPath({
   prerenderer,
   pathname,
@@ -239,7 +301,8 @@ async function renderPath({
     options.origin,
     config.build.format,
     config.trailingSlash,
-    route.type
+    route.type,
+    route.isIndex
   );
   const request = createRequest({
     url,
@@ -249,8 +312,13 @@ async function renderPath({
     routePattern: route.component
   });
   let response;
+  let metadata;
   try {
-    response = await prerenderer.render(request, { routeData: route });
+    const rendered = normalizePrerenderResult(
+      await prerenderer.render(request, { routeData: route })
+    );
+    response = rendered.response;
+    metadata = rendered.metadata;
   } catch (err) {
     logger.error("build", `Caught error rendering ${pathname}: ${err}`);
     if (err && !AstroError.is(err) && !err.id && typeof err === "object") {
@@ -299,16 +367,65 @@ async function renderPath({
     routeToHeaders.set(pathname, { headers: responseHeaders, route: integrationRoute });
   }
   if (checkPublicConflict(outFile, route, options.settings, logger)) return null;
-  return { body, outFile, outFolder };
+  return { body, outFile, outFolder, metadata };
 }
-async function generatePathWithPrerenderer(prerenderer, pathname, route, options, routeToHeaders, logger) {
+async function generatePathWithPrerenderer(prerenderer, pathname, route, options, internals, routeToHeaders, logger, cache, cacheKey) {
   const timeStart = performance.now();
   const { config } = options.settings;
   const filePath = getOutputFilename(config.build.format, pathname, route);
+  const encodedPath = encodeURI(pathname);
+  const outFolder = getOutFolder(options.settings, encodedPath, route);
+  const outFile = getOutFile(config.build.format, outFolder, encodedPath, route);
+  const relativeOutFile = outFile.href.slice(config.outDir.href.length);
+  const dependencyHash = internals.pageDependencyHashes?.get(route.component) ?? "";
+  const hasServerIsland = internals.serverIslandPageComponents?.has(route.component) ?? false;
+  if (cacheKey !== void 0 && cache?.canSkip(route.component, pathname, dependencyHash, cacheKey, hasServerIsland)) {
+    const existsInDist = nodeFs.existsSync(outFile);
+    const restored = !existsInDist && await cache.restoreOutputFile(options.settings, relativeOutFile, outFile);
+    if (existsInDist || restored) {
+      const restoredImages = cache.previousStaticImages(route.component, pathname);
+      if (restoredImages) restoreStaticImages(restoredImages);
+      const restoredHeaders = cache.previousHeaders(route.component, pathname);
+      if (restoredHeaders && options.settings.adapter?.adapterFeatures?.staticHeaders) {
+        routeToHeaders.set(pathname, {
+          headers: new Headers(restoredHeaders),
+          route: toIntegrationResolvedRoute(route, config.trailingSlash)
+        });
+      }
+      cache.record(
+        route.component,
+        dependencyHash,
+        pathname,
+        cacheKey,
+        relativeOutFile,
+        cache.previousContentEntryKeys(route.component, pathname),
+        restoredImages,
+        restoredHeaders
+      );
+      if (route.type === "page") {
+        addPageName(pathname, options);
+      }
+      if (route.distURL) {
+        route.distURL.push(outFile);
+      } else {
+        route.distURL = [outFile];
+      }
+      logger.info(null, `  ${colors.green("\u251C\u2500")} ${colors.dim(filePath)}`, false);
+      logger.info(
+        "SKIP_FORMAT",
+        restored ? ` ${colors.green("(restored)")}` : ` ${colors.green("(cached)")}`
+      );
+      return;
+    }
+  }
   logger.info(null, `  ${colors.blue("\u251C\u2500")} ${colors.dim(filePath)}`, false);
   if (route.type === "page") {
     addPageName(pathname, options);
   }
+  if (cache) {
+    beginContentEntryCollection();
+    beginImageCollection();
+  }
   const result = await renderPath({
     prerenderer,
     pathname,
@@ -317,12 +434,30 @@ async function generatePathWithPrerenderer(prerenderer, pathname, route, options
     routeToHeaders,
     logger
   });
+  const collectedContentEntryKeys = cache ? endContentEntryCollection() : void 0;
+  const collectedStaticImages = cache ? endImageCollection() : void 0;
+  const contentEntryKeys = result?.metadata?.contentEntryKeys ?? collectedContentEntryKeys;
+  const staticImages = result?.metadata?.staticImages ?? collectedStaticImages;
+  const headers = cache ? [...routeToHeaders.get(pathname)?.headers ?? []] : void 0;
   if (!result) {
     logRenderTime(logger, timeStart, true);
     return;
   }
   await nodeFs.promises.mkdir(result.outFolder, { recursive: true });
   await nodeFs.promises.writeFile(result.outFile, result.body);
+  if (cache && cacheKey !== void 0) {
+    await cache.writeOutputFile(options.settings, relativeOutFile, result.body);
+    cache.record(
+      route.component,
+      dependencyHash,
+      pathname,
+      cacheKey,
+      relativeOutFile,
+      contentEntryKeys,
+      staticImages,
+      headers
+    );
+  }
   logRenderTime(logger, timeStart, false);
 }
 function logRenderTime(logger, timeStart, notCreated) {
@@ -338,11 +473,11 @@ function addPageName(pathname, opts) {
   const pageName = shouldAppendForwardSlash(trailingSlash, buildFormat) ? pathname.replace(/\/?$/, "/").replace(/^\//, "") : pathname.replace(/^\//, "");
   opts.pageNames.push(pageName);
 }
-function getUrlForPath(pathname, base, origin, format, trailingSlash, routeType) {
+function getUrlForPath(pathname, base, origin, format, trailingSlash, routeType, isIndex) {
   let ending;
-  switch (format) {
-    case "directory":
-    case "preserve": {
+  const effectiveFormat = format === "preserve" ? isIndex ? "directory" : "file" : format;
+  switch (effectiveFormat) {
+    case "directory": {
       ending = trailingSlash === "never" ? "" : "/";
       break;
     }
@@ -354,7 +489,7 @@ function getUrlForPath(pathname, base, origin, format, trailingSlash, routeType)
   }
   let buildPathname;
   if (pathname === "/" || pathname === "") {
-    if (format === "file") {
+    if (effectiveFormat === "file") {
       buildPathname = joinPaths(base, "index.html");
     } else {
       buildPathname = collapseDuplicateTrailingSlashes(base + ending, trailingSlash !== "never");

package/dist/core/build/incremental-content-collector.d.ts

@@ -0,0 +1,10 @@
+/** Start collecting the content entries rendered on the current path. */
+export declare function beginContentEntryCollection(): void;
+/** Record that a content entry was rendered, keyed by its root-relative `filePath`. */
+export declare function recordContentEntryRender(filePath: string | undefined): void;
+/**
+ * Finish collection and return the rendered entries, or `undefined` when no
+ * collection was active (so callers can distinguish "nothing rendered" from
+ * "not tracked").
+ */
+export declare function endContentEntryCollection(): string[] | undefined;

package/dist/core/build/incremental-content-collector.js

@@ -0,0 +1,33 @@
+const COLLECTOR_KEY = /* @__PURE__ */ Symbol.for("astro:incremental-content-entries");
+function collector() {
+  const host = globalThis;
+  let value = host[COLLECTOR_KEY];
+  if (!value) {
+    value = { current: void 0 };
+    Object.defineProperty(host, COLLECTOR_KEY, {
+      value,
+      configurable: false,
+      writable: false,
+      enumerable: false
+    });
+  }
+  return value;
+}
+function beginContentEntryCollection() {
+  collector().current = /* @__PURE__ */ new Set();
+}
+function recordContentEntryRender(filePath) {
+  if (!filePath) return;
+  collector().current?.add(filePath);
+}
+function endContentEntryCollection() {
+  const c = collector();
+  const entries = c.current;
+  c.current = void 0;
+  return entries ? [...entries] : void 0;
+}
+export {
+  beginContentEntryCollection,
+  endContentEntryCollection,
+  recordContentEntryRender
+};

package/dist/core/build/incremental-image-collector.d.ts

@@ -0,0 +1,11 @@
+import type { SerializedStaticImage } from '../../assets/types.js';
+/** Start collecting the image transforms resolved on the current path. */
+export declare function beginImageCollection(): void;
+/** Record an image transform resolved while rendering the current path. */
+export declare function recordStaticImage(image: SerializedStaticImage): void;
+/**
+ * Finish collection and return the collected transforms, or `undefined` when no
+ * collection was active (so callers can distinguish "no images" from
+ * "not tracked").
+ */
+export declare function endImageCollection(): SerializedStaticImage[] | undefined;