@stati/core 1.27.2 → 1.28.0

package/dist/images/runtime.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Per-build image pipeline: renders image markup while pages render, runs the jobs the
+ * written pages need, recovers from failed jobs and prunes outputs no page uses.
+ * @module images/runtime
+ */
+import type { Eta } from 'eta';
+import type Token from 'markdown-it/lib/token.mjs';
+import type { CacheManifest, GeneratedOgImage, ImageProvider, Logger, OgFont, PageModel, StatiConfig } from '../types/index.js';
+import type { RenderedAssets } from '../core/isg/builder.js';
+import { type ResolvedImagesConfig, type ResolvedOgConfig, type ResolvedResponsiveConfig } from './config.js';
+import { type SourceInfo } from './sources.js';
+import { type CopyPlan, type VariantPlan } from './plan.js';
+/**
+ * Options for `stati.image()` in templates.
+ */
+export interface StatiImageOptions {
+    /** Alternative text; use an empty string for decorative images */
+    alt?: string;
+    /** `sizes` attribute for responsive images */
+    sizes?: string;
+    /** Load eagerly with high fetch priority, for the main image above the fold */
+    priority?: boolean;
+    /** `class` attribute */
+    class?: string;
+    /** `title` attribute */
+    title?: string;
+}
+/** A unit of work that writes one or more files under the output directory. */
+interface JobSpec {
+    key: string;
+    /** Output files, relative to the output directory */
+    outputs: string[];
+    /** Source or page, for messages */
+    label: string;
+    /** Absolute path of the source image, for jobs that copy or encode one */
+    sourcePath?: string;
+    run: () => Promise<void>;
+}
+/** One processed image (or Open Graph card) in a page. */
+interface ImageUse {
+    jobKey: string;
+    outputs: string[];
+    /** A URL the written page contains when it actually uses this image */
+    marker: string;
+    /** Markup core emitted, swapped for `fallbackMarkup` if the job fails */
+    markup?: string;
+    fallbackMarkup?: string;
+    /** Copy the fallback markup needs, for co-located sources */
+    fallbackCopy?: JobSpec;
+    /** Set for Open Graph cards: their tags are removed if the job fails */
+    ogImage?: GeneratedOgImage;
+}
+/** Fonts and template for Open Graph cards, loaded once per build. */
+interface OgState {
+    fonts: OgFont[];
+    fontsHash: string;
+    defaultTemplate: string | undefined;
+}
+/**
+ * Failures found while settling jobs.
+ */
+export interface SettleResult {
+    /** Pages rewritten to fall back to plain images */
+    patchedPages: number;
+    /** Failed jobs, for reporting */
+    failures: Array<{
+        label: string;
+        message: string;
+        og: boolean;
+    }>;
+}
+/**
+ * Checks that og:image URLs will be absolute and public.
+ * @throws {Error} When `site.baseUrl` is not an absolute http(s) URL on a public host
+ */
+export declare function validateOgBaseUrl(baseUrl: string): void;
+/**
+ * Image state for one page while it renders.
+ */
+export declare class PageImages {
+    private readonly runtime;
+    readonly page: PageModel;
+    /** Source files whose content affects the page */
+    readonly assetDeps: Set<string>;
+    /** Processed images and cards, filtered against the written HTML when the page commits */
+    readonly uses: ImageUse[];
+    /** The Markdown image that `eagerFirst` loads eagerly, chosen by `renderMarkdown()` */
+    eagerToken: Token | undefined;
+    private readonly context;
+    constructor(runtime: ImageRuntime, page: PageModel);
+    /**
+     * Renders a Markdown image token.
+     *
+     * @returns The markup, or the `src` to give markdown-it's default renderer when the image
+     *   is left as authored
+     */
+    renderMarkdownImage(token: Token, alt: string): {
+        html: string;
+    } | {
+        src: string;
+    };
+    /**
+     * Implements `stati.image(src, options)` for templates. Synchronous, because templates
+     * print its result directly.
+     */
+    renderHelperImage(src: unknown, options?: StatiImageOptions): string;
+    private renderImage;
+    /**
+     * Whether this page gets a generated Open Graph image.
+     */
+    wantsOg(): boolean;
+    /**
+     * Size of the page's Open Graph image, exposed to the template as `stati.og`.
+     */
+    ogSize(): {
+        width: number;
+        height: number;
+    } | undefined;
+    /**
+     * Renders this page's Open Graph template and registers the card.
+     *
+     * @param context - Template context: the layout's, with an empty body and `stati.og`
+     * @param eta - The template engine
+     * @returns The generated image, or null when the page gets none
+     */
+    renderOg(context: object, eta: Eta): Promise<GeneratedOgImage | null>;
+}
+/**
+ * Options for {@link ImageRuntime.create}.
+ */
+export interface ImageRuntimeOptions {
+    /** Absolute output directory */
+    outDir: string;
+    /** Absolute cache directory (`.stati`) */
+    cacheDir: string;
+    logger: Logger;
+    /** True for dev server builds */
+    development: boolean;
+}
+/**
+ * The image pipeline for one build.
+ */
+export declare class ImageRuntime {
+    readonly settings: ResolvedImagesConfig;
+    readonly provider: ImageProvider | null;
+    readonly ogState: OgState | null;
+    private readonly manifest;
+    private readonly existing;
+    readonly srcDir: string;
+    readonly staticDir: string;
+    readonly outDir: string;
+    private readonly cacheDir;
+    readonly baseUrl: string;
+    readonly logger: Logger;
+    readonly development: boolean;
+    /** Responsive options in effect for this build; null when off or skipped in dev */
+    readonly responsive: ResolvedResponsiveConfig | null;
+    /** Open Graph options in effect for this build; null when off or skipped in dev */
+    readonly og: ResolvedOgConfig | null;
+    /** Counters for the build summary and metrics */
+    readonly stats: {
+        generated: number;
+        cached: number;
+        failed: number;
+    };
+    private readonly specs;
+    /** Source file of each generated image registered this build, by URL path */
+    private readonly generatedSources;
+    private readonly jobs;
+    private readonly failures;
+    private readonly records;
+    private readonly touched;
+    private readonly warned;
+    /** Whether the images manifest changed and needs saving */
+    private dirty;
+    private constructor();
+    /**
+     * Creates the pipeline for a build.
+     *
+     * @returns The runtime, or null when images are turned off with `images: false`
+     * @throws {ConfigValidationError} When the `images` block is invalid
+     * @throws {Error} When a feature needs `@stati/images` and it is missing or incompatible,
+     *   or when an Open Graph font or `site.baseUrl` is unusable
+     */
+    static create(config: StatiConfig, options: ImageRuntimeOptions): Promise<ImageRuntime | null>;
+    /**
+     * Settings that change generated HTML, added to every page's render-inputs hash.
+     */
+    fingerprint(): Record<string, unknown>;
+    /**
+     * Creates the image state for a page about to render.
+     */
+    createPageContext(page: PageModel): PageImages;
+    /**
+     * Whether every generated file a cached page references still exists.
+     */
+    outputsExist(images: readonly string[] | undefined): boolean;
+    /**
+     * Records a written page and starts the jobs for the images its HTML actually contains.
+     *
+     * @param pageImages - The page's image state
+     * @param html - The final HTML of the page
+     * @param info - Output path and cache key of the page
+     * @returns The files to record on the page's cache entry
+     */
+    commitPage(pageImages: PageImages, html: string, info: {
+        outputPath: string;
+        cacheKey: string;
+    }): RenderedAssets;
+    /**
+     * Waits for every job, then rewrites pages whose images failed so they show plain images,
+     * and marks those pages stale so the next build retries.
+     *
+     * @param cacheManifest - The ISG manifest, updated in place
+     */
+    settle(cacheManifest: CacheManifest): Promise<SettleResult>;
+    /**
+     * Saves the images manifest.
+     */
+    save(): Promise<void>;
+    /**
+     * Deletes generated files no page of this build references. Only files recorded in the
+     * images manifest are ever deleted.
+     *
+     * @param liveImages - Generated files referenced by this build's pages
+     * @param liveSources - Source files referenced by this build's pages
+     * @returns Number of files deleted
+     */
+    prune(liveImages: ReadonlySet<string>, liveSources: ReadonlySet<string>): Promise<number>;
+    /**
+     * Inspects a source image and remembers it for the manifest.
+     */
+    inspect(filePath: string): SourceInfo | null;
+    /**
+     * Logs a warning once per build.
+     */
+    warnOnce(key: string, message: string): void;
+    /**
+     * Registers a job. It only runs once a written page references its outputs.
+     */
+    registerJob(spec: JobSpec): void;
+    /**
+     * The source file of an image this build generates, by its URL path, such as
+     * `/_img/hero-1a2b3c4d-960.webp`.
+     */
+    generatedSourceFor(path: string): string | undefined;
+    /**
+     * Job that copies a co-located image to its hashed URL.
+     */
+    copyJob(plan: CopyPlan, sourcePath: string): JobSpec;
+    /**
+     * Job that encodes the responsive variants of an image.
+     */
+    variantJob(plan: VariantPlan, sourcePath: string): JobSpec;
+    private startJob;
+}
+export {};
+//# sourceMappingURL=runtime.d.ts.map

package/dist/images/runtime.d.ts.map

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