@cardanvil/frame-kit 0.2.0

package/dist/manifest/contract.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import { FrameSchema } from "../schema/frame.js";
+/**
+ * Version of the distributable frame format, as `"MAJOR.MINOR"`.
+ *
+ * Deliberately independent of this package's semver: frame-kit will change for
+ * authoring and tooling reasons that do not touch the format on disk.
+ *
+ * - MAJOR changes when a field is removed, renamed, retyped, or given new
+ *   required semantics. A loader must refuse a manifest whose major differs.
+ * - MINOR changes only ever add optional fields. Older loaders stay compatible
+ *   because parsing strips unknown keys; they should warn that the frame may
+ *   render with reduced fidelity.
+ */
+export const CONTRACT_VERSION = "1.0";
+/** The only manifest kind any loader understands today. */
+export const DECLARATIVE_KIND = "declarative";
+export const AssetEntrySchema = z.object({
+    /** Path relative to the directory holding `frame.json`. Always POSIX. */
+    path: z.string(),
+    bytes: z.int().nonnegative().optional(),
+    sha256: z.string().optional(),
+});
+export const FrameManifestSchema = z.object({
+    contractVersion: z.string(),
+    /**
+     * Open on purpose. Future formats (for example a frame that ships code) will
+     * introduce new kinds, and a loader must reject those explicitly — see
+     * {@link assertDeclarative} — rather than failing schema validation, which
+     * would report the wrong problem.
+     */
+    kind: z.string(),
+    /** Stable identifier, reverse-DNS by convention. */
+    id: z.string(),
+    /** The frame's own version, independent of `contractVersion`. */
+    version: z.string(),
+    generator: z.string().optional(),
+    author: z.object({ name: z.string(), url: z.string().optional() }).optional(),
+    /** The frame itself, with every asset URL rewritten to a relative path. */
+    frame: FrameSchema,
+    /** Integrity index for the packaged files. Loaders may ignore it. */
+    assets: z.array(AssetEntrySchema),
+});
+function parseVersion(version) {
+    const match = /^(\d+)\.(\d+)$/.exec(version);
+    if (!match?.[1] || !match[2]) {
+        return undefined;
+    }
+    return { major: Number(match[1]), minor: Number(match[2]) };
+}
+/** Whether a manifest's `contractVersion` can be loaded by this build. */
+export function isContractCompatible(contractVersion, loaderVersion = CONTRACT_VERSION) {
+    const theirs = parseVersion(contractVersion);
+    const ours = parseVersion(loaderVersion);
+    if (!theirs || !ours) {
+        return {
+            ok: false,
+            degraded: false,
+            reason: `malformed contract version: ${contractVersion}`,
+        };
+    }
+    if (theirs.major !== ours.major) {
+        return {
+            ok: false,
+            degraded: false,
+            reason: `contract major ${String(theirs.major)} is not supported by this build (expects ${String(ours.major)})`,
+        };
+    }
+    return {
+        ok: true,
+        degraded: theirs.minor > ours.minor,
+        reason: theirs.minor > ours.minor
+            ? `frame targets contract ${contractVersion}; this build understands ${loaderVersion} and may render it with reduced fidelity`
+            : undefined,
+    };
+}
+/**
+ * Narrows a manifest to one a declarative loader can use.
+ *
+ * Every loader must call this. A manifest of an unknown kind is a manifest
+ * whose `frame` this loader has no business interpreting.
+ */
+export function assertDeclarative(manifest) {
+    if (manifest.kind !== DECLARATIVE_KIND) {
+        throw new Error(`unsupported frame kind ${JSON.stringify(manifest.kind)}; this build only loads ${JSON.stringify(DECLARATIVE_KIND)} frames`);
+    }
+}

package/dist/manifest/deserialize.d.ts

@@ -0,0 +1,19 @@
+import { type Frame } from "../schema/frame.js";
+export interface ManifestToFrameOptions {
+    /**
+     * Turns a package-relative asset path into a URL the renderer can load —
+     * an object URL for a zip, an `asset://` URL for a directory on disk, an
+     * absolute http(s) URL for a remote package.
+     */
+    resolveUrl: (path: string) => string;
+    /**
+     * Called when the manifest targets a newer minor contract than this build.
+     * The frame still loads; some fields may be ignored.
+     */
+    onDegraded?: (reason: string) => void;
+}
+/**
+ * Validates a manifest and rebuilds a loadable {@link Frame} from it, turning
+ * every package-relative asset path back into a URL.
+ */
+export declare function manifestToFrame(manifest: unknown, options: ManifestToFrameOptions): Frame;

package/dist/manifest/deserialize.js

@@ -0,0 +1,23 @@
+import { FrameSchema } from "../schema/frame.js";
+import { FrameManifestSchema, assertDeclarative, isContractCompatible, } from "./contract.js";
+import { setAtPath, walkAssets } from "./walk.js";
+/**
+ * Validates a manifest and rebuilds a loadable {@link Frame} from it, turning
+ * every package-relative asset path back into a URL.
+ */
+export function manifestToFrame(manifest, options) {
+    const parsed = FrameManifestSchema.parse(manifest);
+    const compatibility = isContractCompatible(parsed.contractVersion);
+    if (!compatibility.ok) {
+        throw new Error(compatibility.reason ?? "incompatible contract version");
+    }
+    if (compatibility.degraded && compatibility.reason) {
+        options.onDegraded?.(compatibility.reason);
+    }
+    assertDeclarative(parsed);
+    const frame = JSON.parse(JSON.stringify(parsed.frame));
+    for (const occurrence of walkAssets(FrameSchema, frame)) {
+        setAtPath(frame, occurrence.path, options.resolveUrl(occurrence.url));
+    }
+    return FrameSchema.parse(frame);
+}

package/dist/manifest/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./contract.js";
+export * from "./deserialize.js";
+export * from "./serialize.js";
+export * from "./walk.js";

package/dist/manifest/index.js

@@ -0,0 +1,4 @@
+export * from "./contract.js";
+export * from "./deserialize.js";
+export * from "./serialize.js";
+export * from "./walk.js";

package/dist/manifest/serialize.d.ts

@@ -0,0 +1,35 @@
+import { type Frame } from "../schema/frame.js";
+import { type FrameManifest } from "./contract.js";
+/** Where one asset ended up in the package, and what it contains. */
+export interface PackagedAsset {
+    /** Path relative to the directory holding `frame.json`. POSIX separators. */
+    path: string;
+    bytes?: number;
+    sha256?: string;
+}
+export interface FrameToManifestOptions {
+    id: string;
+    version: string;
+    generator?: string;
+    author?: {
+        name: string;
+        url?: string;
+    };
+    /**
+     * Maps a build-time asset URL to its packaged location.
+     *
+     * Supplied by the caller so this module stays free of filesystem access:
+     * the packaging CLI hashes and copies files, tests pass an in-memory map.
+     * Returning the same path for two URLs is how deduplication happens.
+     */
+    resolveAsset: (url: string) => PackagedAsset;
+}
+/**
+ * Converts an authored {@link Frame} into a distributable manifest, rewriting
+ * every asset URL to a package-relative path.
+ *
+ * The frame is serialized *after* authoring helpers have run, so a loader never
+ * needs them — which is what lets the authoring API evolve without changing the
+ * on-disk format.
+ */
+export declare function frameToManifest(frame: Frame, options: FrameToManifestOptions): FrameManifest;

package/dist/manifest/serialize.js

@@ -0,0 +1,44 @@
+import { FrameSchema } from "../schema/frame.js";
+import { CONTRACT_VERSION, DECLARATIVE_KIND, } from "./contract.js";
+import { formatPath, setAtPath, walkAssets } from "./walk.js";
+/**
+ * Converts an authored {@link Frame} into a distributable manifest, rewriting
+ * every asset URL to a package-relative path.
+ *
+ * The frame is serialized *after* authoring helpers have run, so a loader never
+ * needs them — which is what lets the authoring API evolve without changing the
+ * on-disk format.
+ */
+export function frameToManifest(frame, options) {
+    // Round-trip through JSON to get a plain, mutable copy. Frame configs wire
+    // module namespace objects straight into asset fields (the barrel
+    // convention), and those are neither mutable nor plain.
+    const plain = JSON.parse(JSON.stringify(frame));
+    const assetsByPath = new Map();
+    for (const occurrence of walkAssets(FrameSchema, plain)) {
+        const packaged = options.resolveAsset(occurrence.url);
+        if (!packaged.path) {
+            throw new Error(`resolveAsset returned no path for ${occurrence.url} at ${formatPath(occurrence.path)}`);
+        }
+        setAtPath(plain, occurrence.path, packaged.path);
+        assetsByPath.set(packaged.path, {
+            path: packaged.path,
+            ...(packaged.bytes === undefined ? {} : { bytes: packaged.bytes }),
+            ...(packaged.sha256 === undefined ? {} : { sha256: packaged.sha256 }),
+        });
+    }
+    const rewritten = FrameSchema.parse(plain);
+    return {
+        contractVersion: CONTRACT_VERSION,
+        kind: DECLARATIVE_KIND,
+        id: options.id,
+        version: options.version,
+        ...(options.generator === undefined
+            ? {}
+            : { generator: options.generator }),
+        ...(options.author === undefined ? {} : { author: options.author }),
+        frame: rewritten,
+        // Sorted so the manifest is byte-stable across builds and diffs cleanly.
+        assets: [...assetsByPath.values()].sort((a, b) => a.path.localeCompare(b.path)),
+    };
+}

package/dist/manifest/testFrame.d.ts

@@ -0,0 +1,9 @@
+import type { Frame } from "../schema/frame.js";
+/**
+ * A small but structurally realistic frame for tests: assets in a color set, a
+ * nested mask, a preview image, and styling strings that must NOT be treated as
+ * assets. `base.w` and `base.u` deliberately share one URL so deduplication is
+ * exercised.
+ */
+export declare const SHARED_URL = "/src/frames/shared-border.png";
+export declare const testFrame: Frame;

package/dist/manifest/testFrame.js

@@ -0,0 +1,53 @@
+/**
+ * A small but structurally realistic frame for tests: assets in a color set, a
+ * nested mask, a preview image, and styling strings that must NOT be treated as
+ * assets. `base.w` and `base.u` deliberately share one URL so deduplication is
+ * exercised.
+ */
+export const SHARED_URL = "/src/frames/shared-border.png";
+export const testFrame = {
+    name: "Test Frame",
+    description: "Fixture",
+    previewImage: "/src/frames/preview.jpg",
+    tags: ["test"],
+    templateSettings: {
+        useNyxBorder: {
+            type: "boolean",
+            label: "Use Nyx Border",
+            defaultValue: true,
+        },
+        style: {
+            type: "select",
+            label: "Style",
+            defaultValue: "classic",
+            options: ["classic", "modern"],
+        },
+    },
+    config: {
+        layouts: {
+            normal: {
+                boxes: {
+                    art: { x: 0, y: 0, width: 100, height: 100 },
+                    mana: { x: 0, y: 0, width: 10, height: 10, fontSize: 12 },
+                    title: {
+                        x: 0,
+                        y: 0,
+                        width: 10,
+                        height: 10,
+                        fontSize: 12,
+                        color: "white",
+                        outlineColor: "black",
+                        fontFamily: "Beleren",
+                    },
+                    type: { x: 0, y: 0, width: 10, height: 10, fontSize: 12 },
+                    setSymbol: { x: 0, y: 0, width: 10, height: 10 },
+                },
+                frameAssets: {
+                    base: { w: SHARED_URL, u: SHARED_URL, b: "/src/frames/black.png" },
+                    black: "/src/frames/crown-bar.png",
+                },
+                masks: { pinlines: "/src/frames/pinlines.png" },
+            },
+        },
+    },
+};

package/dist/manifest/walk.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/** Location of a value inside a frame, as a property path. */
+export type FramePath = readonly (string | number)[];
+export interface AssetOccurrence {
+    readonly path: FramePath;
+    readonly url: string;
+}
+/**
+ * Finds every asset URL in `value` by walking `schema` alongside it.
+ *
+ * Driven by the schema rather than by a hard-coded list of field paths, so a
+ * new asset field in the contract is picked up automatically — see
+ * {@link isAssetUrlSchema}.
+ */
+export declare function walkAssets(schema: z.ZodType, value: unknown): AssetOccurrence[];
+/** Reads the value at `path`, or `undefined` if any segment is missing. */
+export declare function getAtPath(root: unknown, path: FramePath): unknown;
+/** Writes `value` at `path`. Every parent segment must already exist. */
+export declare function setAtPath(root: unknown, path: FramePath, value: unknown): void;
+/** Human-readable rendering of a path, for error messages. */
+export declare function formatPath(path: FramePath): string;

package/dist/manifest/walk.js

@@ -0,0 +1,111 @@
+import { isAssetUrlSchema } from "../schema/assetUrl.js";
+function definition(schema) {
+    return schema.def;
+}
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function visit(schema, value, path, out) {
+    const node = definition(schema);
+    switch (node.type) {
+        // Wrappers: same value, one level in.
+        case "optional":
+        case "nullable":
+        case "default":
+        case "prefault":
+        case "readonly":
+        case "nonoptional": {
+            if (node.innerType) {
+                visit(node.innerType, value, path, out);
+            }
+            return;
+        }
+        case "object": {
+            if (!isPlainRecord(value) || !node.shape) {
+                return;
+            }
+            for (const [key, child] of Object.entries(node.shape)) {
+                if (key in value) {
+                    visit(child, value[key], [...path, key], out);
+                }
+            }
+            return;
+        }
+        case "record": {
+            const { valueType } = node;
+            if (!isPlainRecord(value) || !valueType) {
+                return;
+            }
+            for (const [key, child] of Object.entries(value)) {
+                visit(valueType, child, [...path, key], out);
+            }
+            return;
+        }
+        case "array": {
+            const { element } = node;
+            if (!Array.isArray(value) || !element) {
+                return;
+            }
+            value.forEach((item, index) => {
+                visit(element, item, [...path, index], out);
+            });
+            return;
+        }
+        case "union": {
+            // Follow only the branch that actually accepts this value, so a union
+            // never reports assets belonging to a variant the value is not.
+            const match = node.options?.find((option) => option.safeParse(value).success);
+            if (match) {
+                visit(match, value, path, out);
+            }
+            return;
+        }
+        default: {
+            if (typeof value === "string" && isAssetUrlSchema(schema)) {
+                out.push({ path, url: value });
+            }
+        }
+    }
+}
+/**
+ * Finds every asset URL in `value` by walking `schema` alongside it.
+ *
+ * Driven by the schema rather than by a hard-coded list of field paths, so a
+ * new asset field in the contract is picked up automatically — see
+ * {@link isAssetUrlSchema}.
+ */
+export function walkAssets(schema, value) {
+    const found = [];
+    visit(schema, value, [], found);
+    return found;
+}
+/** Reads the value at `path`, or `undefined` if any segment is missing. */
+export function getAtPath(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (!isPlainRecord(current) && !Array.isArray(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return current;
+}
+/** Writes `value` at `path`. Every parent segment must already exist. */
+export function setAtPath(root, path, value) {
+    if (path.length === 0) {
+        throw new Error("setAtPath: empty path");
+    }
+    const parent = getAtPath(root, path.slice(0, -1));
+    if (!isPlainRecord(parent) && !Array.isArray(parent)) {
+        throw new Error(`setAtPath: no container at ${formatPath(path)}`);
+    }
+    const last = path[path.length - 1];
+    if (last === undefined) {
+        throw new Error("setAtPath: empty path segment");
+    }
+    parent[last] = value;
+}
+/** Human-readable rendering of a path, for error messages. */
+export function formatPath(path) {
+    return path.length === 0 ? "<root>" : path.join(".");
+}

package/dist/schema/assetUrl.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/**
+ * Metadata key marking a schema position that holds an image URL rather than
+ * an arbitrary string. Frame configs assign these from bundler asset imports
+ * (`import w from "./w.png"`), so at runtime they are ordinary strings and the
+ * inferred type stays `string`.
+ *
+ * The marker exists so tooling can find every asset in a `Frame` by walking the
+ * schema instead of hard-coding a list of field paths that would silently rot
+ * as the contract grows. Packaging a frame for distribution rewrites exactly
+ * these positions to package-relative paths.
+ */
+export declare const ASSET_URL_META_KEY = "cardAnvilAsset";
+/**
+ * An image URL. Identical to `z.string()` at both the type and validation
+ * level — the only difference is the metadata marker described above.
+ */
+export declare const AssetUrlSchema: z.ZodString;
+export type AssetUrl = z.infer<typeof AssetUrlSchema>;
+/**
+ * Whether a schema position was declared as an asset URL.
+ *
+ * Typed on the core schema interface so it also accepts the results of
+ * unwrapping (`ZodOptional.unwrap()`), which is how callers reach the declared
+ * schema behind an optional field.
+ */
+export declare function isAssetUrlSchema(schema: z.core.$ZodType): boolean;

package/dist/schema/assetUrl.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+/**
+ * Metadata key marking a schema position that holds an image URL rather than
+ * an arbitrary string. Frame configs assign these from bundler asset imports
+ * (`import w from "./w.png"`), so at runtime they are ordinary strings and the
+ * inferred type stays `string`.
+ *
+ * The marker exists so tooling can find every asset in a `Frame` by walking the
+ * schema instead of hard-coding a list of field paths that would silently rot
+ * as the contract grows. Packaging a frame for distribution rewrites exactly
+ * these positions to package-relative paths.
+ */
+export const ASSET_URL_META_KEY = "cardAnvilAsset";
+/**
+ * An image URL. Identical to `z.string()` at both the type and validation
+ * level — the only difference is the metadata marker described above.
+ */
+export const AssetUrlSchema = z.string().meta({ [ASSET_URL_META_KEY]: true });
+/**
+ * Whether a schema position was declared as an asset URL.
+ *
+ * Typed on the core schema interface so it also accepts the results of
+ * unwrapping (`ZodOptional.unwrap()`), which is how callers reach the declared
+ * schema behind an optional field.
+ */
+export function isAssetUrlSchema(schema) {
+    return z.globalRegistry.get(schema)?.[ASSET_URL_META_KEY] === true;
+}