@cardanvil/frame-kit 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Taxiera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# @cardanvil/frame-kit
+
+The contract [Card Anvil](https://github.com/Card-Anvil) frames are authored against: the schemas that
+define what a frame is, the helpers you author one with, and the format frames are distributed in.
+
+```sh
+pnpm add -D @cardanvil/frame-kit zod
+```
+
+`zod` is a peer dependency — the frame types are inferred from zod schemas, so you and this package
+must share one copy.
+
+> **Building a frame?** Start from
+> [Card-Anvil/frame-template](https://github.com/Card-Anvil/frame-template) instead of wiring this up
+> by hand. This package is the contract underneath it.
+
+## A frame is data
+
+A frame is one plain object: box geometry, asset URLs, and a few render knobs. Nothing in it runs at
+render time. That constraint is the whole reason frames are distributable — a frame can be serialized
+to a `frame.json` plus a folder of images and loaded by an app that never compiled it, precisely
+because there is no behaviour to carry across.
+
+```ts
+import { type Frame, withCollectorInfoDefaults } from "@cardanvil/frame-kit";
+
+import preview from "./preview.jpg";
+import { regularLayoutConfig } from "./regular/config";
+
+export const myFrame = {
+  name: "Parchment",
+  description: "A hand-inked parchment frame.",
+  previewImage: preview,
+  tags: ["Custom"],
+  config: {
+    layouts: {
+      normal: withCollectorInfoDefaults(regularLayoutConfig, collectorBounds),
+    },
+  },
+} as const satisfies Frame;
+```
+
+`as const satisfies Frame` is the idiom: `satisfies` checks the object against the contract, `as const`
+keeps the literal types.
+
+## Entry points
+
+| Import                           | What it gives you                                                                                                                                                                    |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@cardanvil/frame-kit`           | The schemas (`FrameSchema`, `LayoutConfigSchema`, `FrameAssetsSchema`, …), the inferred types (`Frame`, `LayoutConfig`, `CardBoxes`, `TextBox`, `Layout`), and the authoring helpers |
+| `@cardanvil/frame-kit/manifest`  | The distributable format: `frameToManifest`, `manifestToFrame`, `walkAssets`, `FrameManifestSchema`, `isContractCompatible`, `assertDeclarative`                                     |
+| `@cardanvil/frame-kit/packaging` | The packaging tools the CLI is built on: `validateFrames`, `buildFrames`, `FrameIndexSchema`. Needs Node and Vite, so it is deliberately not on the main entry point                 |
+
+## The `frame-kit` command
+
+```bash
+frame-kit validate                # check every frame, write nothing
+frame-kit build --out dist        # check, then pack each one
+frame-kit schema meta             # a format as JSON Schema
+frame-kit --help
+```
+
+A frame is any directory holding a `frame.meta.json`, so this works both in a
+workspace of packages and in a flat repository.
+
+`validate` loads every frame through Vite, parses it against `FrameSchema`,
+resolves every asset to a file that exists, and round-trips it through the
+manifest in memory. Problems are collected rather than thrown, so one run
+reports everything; under GitHub Actions they become inline annotations.
+
+`build` adds hashing, zipping and the release index. Each frame becomes a
+`<slug>-<version>.cardframe`, and `frame-index.json` describes the set.
+
+Exit codes: `0` clean, `1` one or more frames failed, `2` used wrongly.
+
+Packaging needs Vite — it is what turns `import w from "./w.png"` into a file —
+so it is an **optional** peer dependency, loaded only when packaging runs. The
+schemas above work under plain Node and in a browser without it.
+
+## Type it, then validate it
+
+Typing a config as `Frame` is weaker than the schema a loading app enforces. The clearest example:
+passing a whole asset barrel to a typed field type-checks even when the barrel exports extra keys,
+because excess property checks do not apply to namespace objects — and those extra keys then enter the
+frame contract where nothing can resolve them.
+
+```ts
+import { FrameSchema } from "@cardanvil/frame-kit";
+
+const result = FrameSchema.safeParse(myFrame);
+expect(result.error?.issues ?? []).toEqual([]);
+```
+
+## The coordinate space
+
+Boxes are **absolute pixels** on a **3264 × 4440** canvas.
+
+⚠ **A Magic card face is 63 × 88 mm** — _not_ 2.5 × 3.5 inches, which is the poker-card size and is
+wrong by 0.5 mm across and 0.9 mm tall, roughly 24 × 43 pixels at 1200 DPI. In inches the card is
+2.48 × 3.46.
+
+The canvas is **not** the card face: it is the full printed sheet **including bleed** — 2.72 × 3.7 in
+(69.09 × 93.98 mm) at 1200 DPI, about 3 mm of bleed per edge. A box at `y: 0` sits in the bleed, above
+the top of the card. Override the canvas per frame with `config.canvas`.
+
+`fontSize` is in **points**, not pixels; the renderer converts.
+
+## The distributable format
+
+`@cardanvil/frame-kit/manifest` converts a `Frame` into something an app can install: a `frame.json`
+with every asset URL rewritten to a package-relative path, plus the files themselves.
+
+Asset positions are found by **walking the schema**, not from a hard-coded list of field paths, so a
+new asset field in the contract is picked up automatically.
+
+```ts
+import { frameToManifest } from "@cardanvil/frame-kit/manifest";
+
+const manifest = frameToManifest(myFrame, {
+  id: "com.example.parchment",
+  version: "1.0.0",
+  resolveAsset: (url) => ({ path: `assets/${hashOf(url)}.png` }),
+});
+```
+
+`manifestToFrame` reverses it, turning package-relative paths back into URLs the renderer can load —
+an object URL for a zip, an `asset://` URL for a directory on disk, an absolute URL for a remote
+package.
+
+A manifest carries a `contractVersion` of the form `MAJOR.MINOR`, independent of this package's
+version. A differing major is refused; a newer minor loads with a reduced-fidelity warning, because
+added fields are always optional. Packaging preserves everything the contract defines and drops
+everything it does not — keys outside the schema do not survive the round trip.
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/Card-Anvil/frames/blob/trunk/LICENSE).

package/dist/authoring/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./layoutDefaults.js";
+export * from "./omit.js";

package/dist/authoring/index.js

@@ -0,0 +1,2 @@
+export * from "./layoutDefaults.js";
+export * from "./omit.js";

package/dist/authoring/layoutDefaults.d.ts

@@ -0,0 +1,6 @@
+import { LayoutConfig, TemplateSettingsConfig, TextBox } from "../schema/frame.js";
+/**
+ * Applies default collector info bounds to a layout config if not specified.
+ */
+export declare function withCollectorInfoDefaults<T extends LayoutConfig>(config: T, defaultCollectorInfoBounds: TextBox): T;
+export declare function withSettingsDefaults<T extends LayoutConfig>(config: T, defaultSettings: TemplateSettingsConfig): T;

package/dist/authoring/layoutDefaults.js

@@ -0,0 +1,80 @@
+/**
+ * Applies default collector info bounds to a layout config if not specified.
+ */
+export function withCollectorInfoDefaults(config, defaultCollectorInfoBounds) {
+    return {
+        ...config,
+        boxes: {
+            ...config.boxes,
+            collectorInfo: config.boxes.collectorInfo ?? defaultCollectorInfoBounds,
+        },
+        tallBoxes: config.tallBoxes
+            ? {
+                ...config.tallBoxes,
+                collectorInfo: config.tallBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+            }
+            : undefined,
+        backBoxes: config.backBoxes
+            ? {
+                ...config.backBoxes,
+                collectorInfo: config.backBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+            }
+            : undefined,
+        sagaFrontBoxes: config.sagaFrontBoxes
+            ? {
+                ...config.sagaFrontBoxes,
+                collectorInfo: config.sagaFrontBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+            }
+            : undefined,
+        sagaBackBoxes: config.sagaBackBoxes
+            ? {
+                ...config.sagaBackBoxes,
+                collectorInfo: config.sagaBackBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+            }
+            : undefined,
+        creatureBoxes: config.creatureBoxes
+            ? {
+                ...config.creatureBoxes,
+                collectorInfo: config.creatureBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+            }
+            : undefined,
+        backCreatureBoxes: config.backCreatureBoxes
+            ? {
+                ...config.backCreatureBoxes,
+                collectorInfo: config.backCreatureBoxes.collectorInfo ??
+                    defaultCollectorInfoBounds,
+            }
+            : undefined,
+        sagaFrontCreatureBoxes: config.sagaFrontCreatureBoxes
+            ? {
+                ...config.sagaFrontCreatureBoxes,
+                collectorInfo: config.sagaFrontCreatureBoxes.collectorInfo ??
+                    defaultCollectorInfoBounds,
+            }
+            : undefined,
+        sagaBackCreatureBoxes: config.sagaBackCreatureBoxes
+            ? {
+                ...config.sagaBackCreatureBoxes,
+                collectorInfo: config.sagaBackCreatureBoxes.collectorInfo ??
+                    defaultCollectorInfoBounds,
+            }
+            : undefined,
+        // Saga layouts swap `boxes` for `flipsidePtBoxes` on face 0 when the
+        // other face has power/toughness (see renderCardToCanvas) — without this,
+        // that swap silently drops collector info whenever it triggers.
+        flipsidePtBoxes: config.flipsidePtBoxes
+            ? {
+                ...config.flipsidePtBoxes,
+                collectorInfo: config.flipsidePtBoxes.collectorInfo ?? defaultCollectorInfoBounds,
+            }
+            : undefined,
+    };
+}
+export function withSettingsDefaults(config, defaultSettings) {
+    const layoutSettings = config.templateSettings ?? {};
+    const mergedSettings = { ...defaultSettings, ...layoutSettings };
+    return {
+        ...config,
+        templateSettings: mergedSettings,
+    };
+}

package/dist/authoring/omit.d.ts

@@ -0,0 +1,2 @@
+/** Returns a copy of `obj` with the given keys removed (non-mutating). */
+export declare function omit<T extends object, K extends keyof T>(obj: T, keys: readonly K[]): Omit<T, K>;

package/dist/authoring/omit.js

@@ -0,0 +1,14 @@
+/** Returns a copy of `obj` with the given keys removed (non-mutating). */
+export function omit(obj, keys) {
+    const keyMap = {};
+    for (const key of keys) {
+        keyMap[key] = true;
+    }
+    const result = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (!(k in keyMap)) {
+            result[k] = v;
+        }
+    }
+    return result;
+}

package/dist/cli/api.d.ts

@@ -0,0 +1,34 @@
+import { type Frame } from "../schema/frame.js";
+import { type DiscoveredFrame } from "./discover.js";
+import { Reporter } from "./report.js";
+export interface LoadedFrame {
+    discovered: DiscoveredFrame;
+    /** The frame as authored, validated against `FrameSchema`. */
+    frame: Frame;
+    /** JSON projection — asset sets are module namespace objects when authored. */
+    plain: unknown;
+    /** Every asset in the frame, resolved to a file that exists. */
+    assets: {
+        url: string;
+        file: string;
+    }[];
+}
+export interface LoadOptions {
+    root: string;
+    /** Restrict to these slugs. Empty means every frame found. */
+    only?: readonly string[];
+}
+/**
+ * Loads, validates and resolves every frame under `root`.
+ *
+ * Shared by `validate` and `build` so the two can never disagree about whether
+ * a frame is sound.
+ */
+export declare function loadFrames(options: LoadOptions, reporter: Reporter): Promise<LoadedFrame[]>;
+export interface ValidateResult {
+    reporter: Reporter;
+    /** The frames that loaded cleanly. Fewer than were found, if some failed. */
+    frames: LoadedFrame[];
+}
+/** Loads every frame and reports what is wrong. Writes nothing. */
+export declare function validateFrames(options: LoadOptions): Promise<ValidateResult>;

package/dist/cli/api.js

@@ -0,0 +1,188 @@
+import { stat } from "node:fs/promises";
+import path from "node:path";
+import { FrameManifestSchema, frameToManifest, manifestToFrame, walkAssets, } from "../manifest/index.js";
+import { FrameSchema } from "../schema/frame.js";
+import { devUrlToFile } from "./devUrl.js";
+import { discoverFrames, relativePosix, } from "./discover.js";
+import { PackagingError } from "./errors.js";
+import { loadFrameExport, startFrameServer, } from "./loadFrame.js";
+import { Reporter } from "./report.js";
+/** Namespace reserved for Card Anvil's own frames. */
+const RESERVED_ID_PREFIX = "com.cardanvil.";
+/** Deep JSON copy: frame configs wire module namespaces into asset fields. */
+function toPlain(frame) {
+    return JSON.parse(JSON.stringify(frame));
+}
+/**
+ * Loads, validates and resolves every frame under `root`.
+ *
+ * Shared by `validate` and `build` so the two can never disagree about whether
+ * a frame is sound.
+ */
+export async function loadFrames(options, reporter) {
+    const root = path.resolve(options.root);
+    const discovered = await discoverFrames(root, reporter);
+    const only = new Set(options.only ?? []);
+    const wanted = only.size === 0
+        ? discovered
+        : discovered.filter((frame) => only.has(frame.slug));
+    for (const slug of only) {
+        if (!discovered.some((frame) => frame.slug === slug)) {
+            reporter.error({ message: `no frame named "${slug}" was found` });
+        }
+    }
+    if (wanted.length === 0) {
+        if (discovered.length === 0) {
+            reporter.error({
+                message: `no frames found under ${root}. A frame is any directory with a ` +
+                    `frame.meta.json in it.`,
+            });
+        }
+        return [];
+    }
+    let frameServer;
+    const loaded = [];
+    try {
+        frameServer = await startFrameServer(root);
+        for (const frame of wanted) {
+            const result = await loadOne(frameServer, root, frame, reporter);
+            if (result) {
+                loaded.push(result);
+            }
+        }
+    }
+    finally {
+        await frameServer?.close();
+    }
+    return loaded;
+}
+async function loadOne(frameServer, root, discovered, reporter) {
+    const slug = discovered.slug;
+    const file = relativePosix(root, discovered.metaFile);
+    const owner = process.env.GITHUB_REPOSITORY_OWNER;
+    if (discovered.meta.id.startsWith(RESERVED_ID_PREFIX) &&
+        owner !== undefined &&
+        owner !== "Card-Anvil") {
+        reporter.warn({
+            frame: slug,
+            file,
+            message: `id "${discovered.meta.id}" is in Card Anvil's own namespace. An id is ` +
+                `permanent and a marketplace binds it to a repository — use your own, ` +
+                `e.g. com.github.${owner}.${slug}.`,
+        });
+    }
+    let exported;
+    try {
+        exported = await loadFrameExport(frameServer, discovered.entryFile, discovered.meta.export);
+    }
+    catch (cause) {
+        reporter.error({
+            frame: slug,
+            file,
+            message: cause instanceof PackagingError ? cause.message : String(cause),
+        });
+        return undefined;
+    }
+    const parsed = FrameSchema.safeParse(exported);
+    if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+            reporter.error({
+                frame: slug,
+                file: relativePosix(root, discovered.entryFile),
+                path: issue.path.join(".") || undefined,
+                message: issue.message,
+            });
+        }
+        return undefined;
+    }
+    const plain = toPlain(parsed.data);
+    const assets = await resolveAssets(frameServer, root, slug, plain, reporter);
+    if (!assets) {
+        return undefined;
+    }
+    if (!roundTrips(slug, plain, assets, reporter)) {
+        return undefined;
+    }
+    return { discovered, frame: parsed.data, plain, assets };
+}
+/** Maps every asset URL to a file, and proves each one exists. */
+async function resolveAssets(frameServer, root, slug, plain, reporter) {
+    const occurrences = walkAssets(FrameSchema, plain);
+    const byUrl = new Map();
+    let failed = false;
+    for (const occurrence of occurrences) {
+        if (byUrl.has(occurrence.url)) {
+            continue;
+        }
+        let file;
+        try {
+            file = devUrlToFile(occurrence.url, frameServer.root, frameServer.base);
+        }
+        catch (cause) {
+            reporter.error({
+                frame: slug,
+                path: occurrence.path.join("."),
+                message: cause instanceof PackagingError ? cause.message : String(cause),
+            });
+            failed = true;
+            continue;
+        }
+        try {
+            const stats = await stat(file);
+            if (!stats.isFile()) {
+                throw new Error("not a file");
+            }
+        }
+        catch {
+            reporter.error({
+                frame: slug,
+                path: occurrence.path.join("."),
+                message: `file not found: ${relativePosix(root, file)}`,
+            });
+            failed = true;
+            continue;
+        }
+        byUrl.set(occurrence.url, file);
+    }
+    return failed ? undefined : [...byUrl].map(([url, file]) => ({ url, file }));
+}
+/**
+ * Packs and unpacks the frame in memory, proving the bundle it would produce is
+ * one a loader could actually read back. `build` repeats this on the real
+ * manifest, so a build never emits an unloadable bundle.
+ */
+function roundTrips(slug, plain, assets, reporter) {
+    const paths = new Map(assets.map(({ url, file }, index) => [
+        url,
+        `assets/${String(index)}${path.extname(file).toLowerCase()}`,
+    ]));
+    try {
+        const manifest = frameToManifest(plain, {
+            id: "com.example.check",
+            version: "0.0.0",
+            resolveAsset: (url) => {
+                const packaged = paths.get(url);
+                if (packaged === undefined) {
+                    throw new PackagingError(`unresolved asset ${url}`);
+                }
+                return { path: packaged };
+            },
+        });
+        FrameManifestSchema.parse(JSON.parse(JSON.stringify(manifest)));
+        manifestToFrame(manifest, { resolveUrl: (packaged) => packaged });
+        return true;
+    }
+    catch (cause) {
+        reporter.error({
+            frame: slug,
+            message: `cannot be packaged: ${cause instanceof Error ? cause.message : String(cause)}`,
+        });
+        return false;
+    }
+}
+/** Loads every frame and reports what is wrong. Writes nothing. */
+export async function validateFrames(options) {
+    const reporter = new Reporter();
+    const frames = await loadFrames(options, reporter);
+    return { reporter, frames };
+}

package/dist/cli/build.d.ts

@@ -0,0 +1,36 @@
+import { type FrameManifest } from "../manifest/index.js";
+import { type LoadOptions, type LoadedFrame } from "./api.js";
+import { type FrameIndex, type IndexedFrame, type ReleaseSource } from "./frameIndex.js";
+import type { Reporter } from "./report.js";
+export interface BuildOptions extends LoadOptions {
+    /** Directory bundles and the index are written to. Created if missing. */
+    outDir: string;
+    /** Stamped into every manifest. One version for every frame in the repo. */
+    version: string;
+    generator?: string;
+    /** Where the release will live. Omitted for a local build. */
+    source?: ReleaseSource;
+}
+export interface BuiltFrame {
+    loaded: LoadedFrame;
+    manifest: FrameManifest;
+    /** Absolute path to the written bundle. */
+    bundleFile: string;
+    /** Filename only, which is what a release asset is addressed by. */
+    bundleName: string;
+    bytes: number;
+    /** This frame's row in the release index. */
+    entry: IndexedFrame;
+}
+export interface BuildResult {
+    frames: BuiltFrame[];
+    /** Written to `<out>/frame-index.json` unless nothing built. */
+    index?: FrameIndex;
+}
+/**
+ * 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 declare function buildFrames(options: BuildOptions, reporter: Reporter): Promise<BuildResult>;