@cardanvil/frame-kit 0.2.0

package/dist/cli/build.js

@@ -0,0 +1,222 @@
+import { copyFile, mkdir, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { FrameManifestSchema, frameToManifest, manifestToFrame, } from "../manifest/index.js";
+import { DEFAULT_CANVAS_HEIGHT, DEFAULT_CANVAS_WIDTH, } from "../schema/frame.js";
+import { loadFrames } from "./api.js";
+import { describeBytes, writeBundle } from "./bundle.js";
+import { PackagingError } from "./errors.js";
+import { FRAME_INDEX_FILENAME, buildIndex, downloadBase, } from "./frameIndex.js";
+import { hashFile, mapWithConcurrency } from "./hash.js";
+import { readImageSize } from "./imageSize.js";
+import { stableStringify } from "./stableJson.js";
+/** How many characters of the sha256 name a packaged asset. 64 bits. */
+const HASH_PREFIX_LENGTH = 16;
+/** GitHub refuses individual repository files above 100 MB. */
+const MAX_ASSET_BYTES = 100 * 1024 * 1024;
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+/**
+ * Packs every sound frame into a `.cardframe` bundle.
+ *
+ * Frames that fail to load are reported and skipped rather than aborting the
+ * run, so one bad frame does not hide the state of the others.
+ */
+export async function buildFrames(options, reporter) {
+    if (!VERSION_PATTERN.test(options.version)) {
+        throw new PackagingError(`"${options.version}" is not a version. Expected MAJOR.MINOR.PATCH, ` +
+            `optionally with a pre-release suffix.`);
+    }
+    const loaded = await loadFrames(options, reporter);
+    const outDir = path.resolve(options.outDir);
+    await mkdir(outDir, { recursive: true });
+    const built = [];
+    for (const frame of loaded) {
+        const result = await buildOne(frame, outDir, options, reporter);
+        if (result) {
+            built.push(result);
+        }
+    }
+    if (built.length === 0) {
+        return { frames: built };
+    }
+    const index = buildIndex({
+        version: options.version,
+        ...(options.generator === undefined
+            ? {}
+            : { generator: options.generator }),
+        ...(options.source === undefined ? {} : { source: options.source }),
+        frames: built.map((frame) => frame.entry),
+    });
+    await writeFile(path.join(outDir, FRAME_INDEX_FILENAME), stableStringify(index), "utf8");
+    return { frames: built, index };
+}
+async function buildOne(loaded, outDir, options, reporter) {
+    const slug = loaded.discovered.slug;
+    const packaged = await packageAssets(loaded, slug, reporter);
+    if (!packaged) {
+        return undefined;
+    }
+    const { byUrl, fileByPath } = packaged;
+    let manifest;
+    try {
+        manifest = frameToManifest(loaded.plain, {
+            id: loaded.discovered.meta.id,
+            version: options.version,
+            ...(options.generator === undefined
+                ? {}
+                : { generator: options.generator }),
+            author: loaded.discovered.meta.author,
+            resolveAsset: (url) => {
+                const asset = byUrl.get(url);
+                if (asset === undefined) {
+                    throw new PackagingError(`unresolved asset ${url}`);
+                }
+                return asset;
+            },
+        });
+        // Prove the bundle is one a loader could read back — on the real manifest,
+        // through JSON, so anything non-serializable is caught too.
+        const roundTripped = JSON.parse(stableStringify(manifest));
+        FrameManifestSchema.parse(roundTripped);
+        manifestToFrame(roundTripped, { resolveUrl: (assetPath) => assetPath });
+    }
+    catch (cause) {
+        reporter.error({
+            frame: slug,
+            message: `cannot be packaged: ${cause instanceof Error ? cause.message : String(cause)}`,
+        });
+        return undefined;
+    }
+    const bundleName = `${slug}-${options.version}.cardframe`;
+    const bundleFile = path.join(outDir, bundleName);
+    try {
+        const { bytes, large } = await writeBundle(bundleFile, manifest, {
+            fileByPath,
+        });
+        if (large) {
+            reporter.warn({
+                frame: slug,
+                message: `${bundleName} is ${describeBytes(bytes)}. It will publish, but that ` +
+                    `is a long download for someone trying the frame out.`,
+            });
+        }
+        const entry = await indexEntry(loaded, manifest, { bundleName, bundleFile, bytes }, fileByPath, outDir, options);
+        return { loaded, manifest, bundleFile, bundleName, bytes, entry };
+    }
+    catch (cause) {
+        reporter.error({
+            frame: slug,
+            message: cause instanceof Error ? cause.message : String(cause),
+        });
+        return undefined;
+    }
+}
+/**
+ * Hashes every asset and decides where it lands in the bundle.
+ *
+ * Runs as a pre-pass because `frameToManifest`'s `resolveAsset` is synchronous
+ * and hashing is not. Naming an asset after its content means deduplication
+ * needs no bookkeeping — two identical files simply claim the same path — and
+ * makes the output independent of traversal order.
+ */
+async function packageAssets(loaded, slug, reporter) {
+    const byUrl = new Map();
+    const byFile = new Map();
+    const fileByPath = new Map();
+    const hashByPath = new Map();
+    // A list rather than a boolean: the worker runs inside a callback, where a
+    // flag assignment does not survive TypeScript's narrowing.
+    const failures = [];
+    await mapWithConcurrency(loaded.assets, 8, async ({ url, file }) => {
+        const seen = byFile.get(file);
+        if (seen) {
+            byUrl.set(url, seen);
+            return;
+        }
+        try {
+            const { size } = await stat(file);
+            if (size > MAX_ASSET_BYTES) {
+                reporter.error({
+                    frame: slug,
+                    message: `${path.basename(file)} is ${describeBytes(size)}, over GitHub's ` +
+                        `100 MB limit for a single file.`,
+                });
+                failures.push(file);
+                return;
+            }
+            const sha256 = await hashFile(file);
+            const assetPath = `assets/${sha256.slice(0, HASH_PREFIX_LENGTH)}${path
+                .extname(file)
+                .toLowerCase()}`;
+            const clash = hashByPath.get(assetPath);
+            if (clash !== undefined && clash !== sha256) {
+                throw new PackagingError(`two different assets hash to ${assetPath}. This should not happen; ` +
+                    `please report it.`);
+            }
+            hashByPath.set(assetPath, sha256);
+            const asset = { path: assetPath, bytes: size, sha256 };
+            byFile.set(file, asset);
+            byUrl.set(url, asset);
+            fileByPath.set(assetPath, file);
+        }
+        catch (cause) {
+            reporter.error({
+                frame: slug,
+                message: cause instanceof Error ? cause.message : String(cause),
+            });
+            failures.push(file);
+        }
+    });
+    return failures.length > 0 ? undefined : { byUrl, fileByPath };
+}
+/**
+ * Builds one frame's row in the release index, and copies its preview out of
+ * the bundle so a browse UI can show the frame without downloading it.
+ */
+async function indexEntry(loaded, manifest, bundle, fileByPath, outDir, options) {
+    const { meta, slug } = loaded.discovered;
+    const previewSource = fileByPath.get(manifest.frame.previewImage);
+    if (previewSource === undefined) {
+        throw new PackagingError(`the preview image is not among the packaged assets — this is a bug in frame-kit`);
+    }
+    const previewName = `${slug}-${options.version}.preview${path.extname(previewSource).toLowerCase()}`;
+    await copyFile(previewSource, path.join(outDir, previewName));
+    const [previewHash, previewStats, size, bundleHash] = await Promise.all([
+        hashFile(previewSource),
+        stat(previewSource),
+        readImageSize(previewSource),
+        hashFile(bundle.bundleFile),
+    ]);
+    const base = options.source === undefined ? undefined : downloadBase(options.source);
+    const withUrl = (artifact) => base === undefined
+        ? artifact
+        : { ...artifact, url: `${base}${artifact.file}` };
+    return {
+        id: meta.id,
+        slug,
+        name: manifest.frame.name,
+        description: manifest.frame.description,
+        version: options.version,
+        tags: [...manifest.frame.tags],
+        layouts: Object.keys(manifest.frame.config.layouts).sort(),
+        canvas: manifest.frame.config.canvas ?? {
+            width: DEFAULT_CANVAS_WIDTH,
+            height: DEFAULT_CANVAS_HEIGHT,
+        },
+        author: meta.author,
+        license: meta.license,
+        ...(meta.homepage === undefined ? {} : { homepage: meta.homepage }),
+        contractVersion: manifest.contractVersion,
+        assetCount: manifest.assets.length,
+        bundle: withUrl({
+            file: bundle.bundleName,
+            bytes: bundle.bytes,
+            sha256: bundleHash,
+        }),
+        preview: withUrl({
+            file: previewName,
+            bytes: previewStats.size,
+            sha256: previewHash,
+            ...(size ?? {}),
+        }),
+    };
+}

package/dist/cli/bundle.d.ts

@@ -0,0 +1,23 @@
+import type { FrameManifest } from "../manifest/contract.js";
+export interface BundleSource {
+    /** Where the asset lives now, keyed by its path inside the bundle. */
+    fileByPath: ReadonlyMap<string, string>;
+}
+export interface BundleResult {
+    bytes: number;
+    /** True when the bundle is large enough to be worth mentioning. */
+    large: boolean;
+}
+/**
+ * Writes a `.cardframe`: the manifest, then every asset it names.
+ *
+ * Assets are **stored, not deflated**. PNG and JPEG are already compressed, so
+ * re-deflating hundreds of megabytes buys about a percent, costs minutes of
+ * CPU, and makes the output depend on the zlib version. Storing them keeps
+ * packing IO-bound and leaves the archive readable without inflating.
+ * `frame.json` is text and deflates roughly ten to one, so it stays compressed.
+ *
+ * Fixed timestamps and modes mean the same source produces the same bytes.
+ */
+export declare function writeBundle(outFile: string, manifest: FrameManifest, source: BundleSource): Promise<BundleResult>;
+export declare function describeBytes(bytes: number): string;

package/dist/cli/bundle.js

@@ -0,0 +1,58 @@
+import { createWriteStream } from "node:fs";
+import { pipeline } from "node:stream/promises";
+import yazl from "yazl";
+import { PackagingError } from "./errors.js";
+import { stableStringify } from "./stableJson.js";
+/** The earliest instant a DOS timestamp can express. */
+const ZIP_EPOCH = new Date(Date.UTC(1980, 0, 1));
+/** GitHub refuses release assets above this. */
+const MAX_BUNDLE_BYTES = 2 * 1024 * 1024 * 1024;
+/** Worth telling an author about long before they hit the hard limit. */
+const WARN_BUNDLE_BYTES = 500 * 1024 * 1024;
+/**
+ * Writes a `.cardframe`: the manifest, then every asset it names.
+ *
+ * Assets are **stored, not deflated**. PNG and JPEG are already compressed, so
+ * re-deflating hundreds of megabytes buys about a percent, costs minutes of
+ * CPU, and makes the output depend on the zlib version. Storing them keeps
+ * packing IO-bound and leaves the archive readable without inflating.
+ * `frame.json` is text and deflates roughly ten to one, so it stays compressed.
+ *
+ * Fixed timestamps and modes mean the same source produces the same bytes.
+ */
+export async function writeBundle(outFile, manifest, source) {
+    const zip = new yazl.ZipFile();
+    zip.addBuffer(Buffer.from(stableStringify(manifest), "utf8"), "frame.json", {
+        mtime: ZIP_EPOCH,
+        mode: 0o100644,
+        compress: true,
+    });
+    // `manifest.assets` is already sorted by path, so entry order is stable.
+    for (const asset of manifest.assets) {
+        const file = source.fileByPath.get(asset.path);
+        if (file === undefined) {
+            throw new PackagingError(`no source file for bundle entry ${asset.path} — this is a bug in frame-kit`);
+        }
+        // yazl stats the file itself; `size` is only for stream entries.
+        zip.addFile(file, asset.path, {
+            mtime: ZIP_EPOCH,
+            mode: 0o100644,
+            compress: false,
+        });
+    }
+    zip.end();
+    let bytes = 0;
+    zip.outputStream.on("data", (chunk) => {
+        bytes += chunk.length;
+    });
+    await pipeline(zip.outputStream, createWriteStream(outFile));
+    if (bytes > MAX_BUNDLE_BYTES) {
+        throw new PackagingError(`${outFile} is ${describeBytes(bytes)}, over GitHub's 2 GiB limit for a ` +
+            `release asset. Split the frame, or use smaller art.`);
+    }
+    return { bytes, large: bytes > WARN_BUNDLE_BYTES };
+}
+export function describeBytes(bytes) {
+    const mb = bytes / (1024 * 1024);
+    return mb >= 1024 ? `${(mb / 1024).toFixed(2)} GiB` : `${mb.toFixed(1)} MB`;
+}

package/dist/cli/devUrl.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reverses Vite's `fileToDevUrl`, turning the URL a frame's asset import
+ * resolved to back into the file on disk it came from.
+ *
+ * In serve mode an asset under `root` becomes `base` + its POSIX path relative
+ * to root; anything outside root becomes `/@fs/` + its absolute path. The URL
+ * is built from the raw module id, so an import query rides along and has to be
+ * stripped.
+ */
+export declare function devUrlToFile(url: string, root: string, base: string): string;

package/dist/cli/devUrl.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+import { PackagingError } from "./errors.js";
+/** Vite's prefix for files outside the project root. */
+const FS_PREFIX = "/@fs/";
+/** Matches a Windows drive letter at the start of a path. */
+const DRIVE_LETTER = /^[a-zA-Z]:/;
+/**
+ * Reverses Vite's `fileToDevUrl`, turning the URL a frame's asset import
+ * resolved to back into the file on disk it came from.
+ *
+ * In serve mode an asset under `root` becomes `base` + its POSIX path relative
+ * to root; anything outside root becomes `/@fs/` + its absolute path. The URL
+ * is built from the raw module id, so an import query rides along and has to be
+ * stripped.
+ */
+export function devUrlToFile(url, root, base) {
+    const pathname = url.split("?", 1)[0] ?? "";
+    if (pathname.startsWith("data:")) {
+        throw new PackagingError(`${url} is a data URL, not a file. The packager turns Vite's inline ` +
+            `limit off, so this is an explicit \`?inline\` import — drop the suffix ` +
+            `so the asset stays a real file.`);
+    }
+    if (/^[a-z][a-z0-9+.-]*:/i.test(pathname)) {
+        throw new PackagingError(`${url} points somewhere remote. A frame has to ship its own art, ` +
+            `because the bundle is what gets installed — remote URLs cannot be ` +
+            `packaged.`);
+    }
+    const decoded = decodeURIComponent(pathname);
+    if (decoded.startsWith(FS_PREFIX)) {
+        // `path.posix.join` built this, and it collapsed the double slash: a POSIX
+        // path lost its leading slash and needs it back, while a Windows path
+        // already carries its own drive letter.
+        const rest = decoded.slice(FS_PREFIX.length);
+        return path.resolve(DRIVE_LETTER.test(rest) ? rest : `/${rest}`);
+    }
+    if (!decoded.startsWith(base)) {
+        throw new PackagingError(`${url} is not under the dev base ${base}, so it cannot be mapped back ` +
+            `to a file.`);
+    }
+    return path.resolve(root, decoded.slice(base.length));
+}

package/dist/cli/discover.d.ts

@@ -0,0 +1,25 @@
+import { type FrameMeta } from "../schema/frameMeta.js";
+import type { Reporter } from "./report.js";
+export interface DiscoveredFrame {
+    /** Names the bundle file. From `meta.slug`, else the directory basename. */
+    slug: string;
+    /** Absolute directory holding the descriptor. */
+    dir: string;
+    /** Absolute path to the descriptor, for error messages. */
+    metaFile: string;
+    /** Absolute path to the module exporting the frame. */
+    entryFile: string;
+    meta: FrameMeta;
+}
+/** Path relative to `root` with POSIX separators, for messages and annotations. */
+export declare function relativePosix(root: string, file: string): string;
+/**
+ * Finds every frame under `root`.
+ *
+ * Marker-file driven rather than convention-guessed, because packaging has to
+ * work both in a workspace of packages and in a flat single-package repository.
+ *
+ * Every malformed descriptor and every collision is reported, not just the
+ * first — an author fixing their repo wants the whole list.
+ */
+export declare function discoverFrames(root: string, reporter: Reporter): Promise<DiscoveredFrame[]>;

package/dist/cli/discover.js

@@ -0,0 +1,116 @@
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { FRAME_META_FILENAME, FrameMetaSchema, } from "../schema/frameMeta.js";
+/** Directories never worth walking into when looking for frames. */
+const SKIP = new Set([
+    "node_modules",
+    "dist",
+    ".git",
+    ".pnpm-store",
+    // The conventional name for test fixtures. A fixture frame exists to be
+    // packaged by a test, not to be shipped by whoever owns the repository.
+    "__fixtures__",
+]);
+/** Path relative to `root` with POSIX separators, for messages and annotations. */
+export function relativePosix(root, file) {
+    return path.relative(root, file).split(path.sep).join("/");
+}
+async function findMetaFiles(dir, out) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // unreadable directory: nothing to discover, not worth failing over
+    }
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (!SKIP.has(entry.name) && !entry.name.startsWith(".")) {
+                await findMetaFiles(path.join(dir, entry.name), out);
+            }
+        }
+        else if (entry.name === FRAME_META_FILENAME) {
+            out.push(path.join(dir, entry.name));
+        }
+    }
+}
+/**
+ * Finds every frame under `root`.
+ *
+ * Marker-file driven rather than convention-guessed, because packaging has to
+ * work both in a workspace of packages and in a flat single-package repository.
+ *
+ * Every malformed descriptor and every collision is reported, not just the
+ * first — an author fixing their repo wants the whole list.
+ */
+export async function discoverFrames(root, reporter) {
+    const metaFiles = [];
+    await findMetaFiles(root, metaFiles);
+    metaFiles.sort((a, b) => a.localeCompare(b));
+    const frames = [];
+    for (const metaFile of metaFiles) {
+        const file = relativePosix(root, metaFile);
+        let raw;
+        try {
+            raw = JSON.parse(await readFile(metaFile, "utf8"));
+        }
+        catch (cause) {
+            reporter.error({
+                file,
+                message: `is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`,
+            });
+            continue;
+        }
+        const parsed = FrameMetaSchema.safeParse(raw);
+        if (!parsed.success) {
+            for (const issue of parsed.error.issues) {
+                reporter.error({
+                    file,
+                    path: issue.path.join(".") || undefined,
+                    message: issue.message,
+                });
+            }
+            continue;
+        }
+        const dir = path.dirname(metaFile);
+        frames.push({
+            slug: parsed.data.slug ?? path.basename(dir),
+            dir,
+            metaFile,
+            entryFile: path.resolve(dir, parsed.data.entry),
+            meta: parsed.data,
+        });
+    }
+    reportCollisions(root, frames, reporter);
+    return frames;
+}
+function reportCollisions(root, frames, reporter) {
+    for (const [key, label] of [
+        ["id", "id"],
+        ["slug", "slug"],
+    ]) {
+        const seen = new Map();
+        for (const frame of frames) {
+            const value = key === "id" ? frame.meta.id : frame.slug;
+            seen.set(value, [...(seen.get(value) ?? []), frame]);
+        }
+        for (const [value, group] of seen) {
+            if (group.length < 2) {
+                continue;
+            }
+            const where = group
+                .map((frame) => relativePosix(root, frame.metaFile))
+                .join(", ");
+            for (const frame of group) {
+                reporter.error({
+                    frame: frame.slug,
+                    file: relativePosix(root, frame.metaFile),
+                    message: `${label} "${value}" is claimed by more than one frame (${where}). ` +
+                        (label === "slug"
+                            ? 'Set a distinct "slug" — it names the bundle file.'
+                            : "An id is permanent identity; two frames cannot share one."),
+                });
+            }
+        }
+    }
+}

package/dist/cli/emitSchemas.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/emitSchemas.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { SHIPPED_SCHEMAS, schemaFilename, toJsonSchema } from "./schema.js";
+import { stableStringify } from "./stableJson.js";
+/** Run at build time so the published package carries its own JSON Schema. */
+const outDir = path.join(import.meta.dirname, "../../schema");
+await mkdir(outDir, { recursive: true });
+for (const name of SHIPPED_SCHEMAS) {
+    const file = path.join(outDir, schemaFilename(name));
+    await writeFile(file, stableStringify(toJsonSchema(name)), "utf8");
+    console.log(`schema: ${schemaFilename(name)}`);
+}

package/dist/cli/errors.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A problem the author can act on: a missing file, an unpackageable asset, a
+ * malformed descriptor. Distinct from a programming error so the CLI can print
+ * it plainly instead of dumping a stack.
+ */
+export declare class PackagingError extends Error {
+    constructor(message: string);
+}

package/dist/cli/errors.js

@@ -0,0 +1,11 @@
+/**
+ * A problem the author can act on: a missing file, an unpackageable asset, a
+ * malformed descriptor. Distinct from a programming error so the CLI can print
+ * it plainly instead of dumping a stack.
+ */
+export class PackagingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PackagingError";
+    }
+}

package/dist/cli/frameIndex.d.ts

@@ -0,0 +1,115 @@
+import { z } from "zod";
+/** Bumped only when the index's own shape changes, not the frame contract's. */
+export declare const FRAME_INDEX_FORMAT_VERSION = 1;
+export declare const FRAME_INDEX_FILENAME = "frame-index.json";
+export declare const IndexedFrameSchema: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    version: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    layouts: z.ZodArray<z.ZodString>;
+    canvas: z.ZodObject<{
+        width: z.ZodInt;
+        height: z.ZodInt;
+    }, z.core.$strip>;
+    author: z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    license: z.ZodString;
+    homepage: z.ZodOptional<z.ZodString>;
+    contractVersion: z.ZodString;
+    assetCount: z.ZodInt;
+    bundle: z.ZodObject<{
+        file: z.ZodString;
+        url: z.ZodOptional<z.ZodURL>;
+        bytes: z.ZodInt;
+        sha256: z.ZodString;
+    }, z.core.$strip>;
+    preview: z.ZodObject<{
+        file: z.ZodString;
+        url: z.ZodOptional<z.ZodURL>;
+        bytes: z.ZodInt;
+        sha256: z.ZodString;
+        width: z.ZodOptional<z.ZodInt>;
+        height: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type IndexedFrame = z.infer<typeof IndexedFrameSchema>;
+export declare const FrameIndexSchema: z.ZodObject<{
+    app: z.ZodLiteral<"card-anvil">;
+    kind: z.ZodLiteral<"frame-index">;
+    formatVersion: z.ZodInt;
+    generatedAt: z.ZodString;
+    generator: z.ZodOptional<z.ZodString>;
+    contractVersion: z.ZodString;
+    version: z.ZodString;
+    source: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodLiteral<"github-release">;
+        repository: z.ZodString;
+        tag: z.ZodString;
+        url: z.ZodURL;
+        downloadBase: z.ZodURL;
+        latestIndexUrl: z.ZodURL;
+    }, z.core.$strip>>;
+    frames: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        version: z.ZodString;
+        tags: z.ZodArray<z.ZodString>;
+        layouts: z.ZodArray<z.ZodString>;
+        canvas: z.ZodObject<{
+            width: z.ZodInt;
+            height: z.ZodInt;
+        }, z.core.$strip>;
+        author: z.ZodObject<{
+            name: z.ZodString;
+            url: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+        license: z.ZodString;
+        homepage: z.ZodOptional<z.ZodString>;
+        contractVersion: z.ZodString;
+        assetCount: z.ZodInt;
+        bundle: z.ZodObject<{
+            file: z.ZodString;
+            url: z.ZodOptional<z.ZodURL>;
+            bytes: z.ZodInt;
+            sha256: z.ZodString;
+        }, z.core.$strip>;
+        preview: z.ZodObject<{
+            file: z.ZodString;
+            url: z.ZodOptional<z.ZodURL>;
+            bytes: z.ZodInt;
+            sha256: z.ZodString;
+            width: z.ZodOptional<z.ZodInt>;
+            height: z.ZodOptional<z.ZodInt>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type FrameIndex = z.infer<typeof FrameIndexSchema>;
+export interface ReleaseSource {
+    /** `owner/name`. */
+    repository: string;
+    /** `vX.Y.Z`. */
+    tag: string;
+}
+/** Where a release's assets are downloadable from. */
+export declare function downloadBase(source: ReleaseSource): string;
+/**
+ * The stable URL a marketplace polls: GitHub resolves `latest` to the newest
+ * published, non-prerelease release, so it needs no API call and no auth. This
+ * is the same convention Card Anvil's own updater relies on.
+ */
+export declare function latestIndexUrl(repository: string): string;
+export declare function buildSource(source: ReleaseSource): FrameIndex["source"];
+export declare function buildIndex(options: {
+    version: string;
+    generator?: string;
+    frames: IndexedFrame[];
+    source?: ReleaseSource;
+    generatedAt?: Date;
+}): FrameIndex;