@cardanvil/frame-kit 0.2.0

package/dist/schema/frameAssets.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { AssetUrlSchema } from "./assetUrl.js";
+/**
+ * Canonical frame color codes: WUBRG, gold (m), artifact (a), colorless (c),
+ * land (l), vehicle (v). Land is always the lowercase "l" — some legacy configs
+ * also shipped an uppercase "L" alias pointing at the same art, but the nested
+ * configs standardize on "l".
+ */
+export const FRAME_COLORS = [
+    "w",
+    "u",
+    "b",
+    "r",
+    "g",
+    "m",
+    "a",
+    "c",
+    "l",
+    "v",
+];
+export const FrameColorEnum = z.enum(FRAME_COLORS);
+/** Image URLs keyed by frame color. Every frame family is a (partial) color set. */
+export const ColorSetSchema = z.partialRecord(FrameColorEnum, AssetUrlSchema);
+/**
+ * Scryfall `frame_effects` values that name a specific transform-DFC icon
+ * variant (mirrors `ScryfallFrameEffect`'s `*Dfc` members, plus `fandfc`).
+ */
+export const DFC_ICON_EFFECTS = [
+    "convertdfc",
+    "sunmoondfc",
+    "compasslanddfc",
+    "originpwdfc",
+    "mooneldrazidfc",
+    "waxingandwaningmoondfc",
+    "fandfc",
+    "upsidedowndfc",
+];
+export const DfcIconEffectEnum = z.enum(DFC_ICON_EFFECTS);
+/** DFC icon image URLs keyed by which `frame_effects` variant they render. */
+export const DfcIconSetSchema = z.partialRecord(DfcIconEffectEnum, AssetUrlSchema);
+/**
+ * Base frames additionally allow "c2" — the hybrid title/type wash used by the
+ * two-color hybrid split rendering. "c2" only ever exists in the base family.
+ */
+export const BASE_COLORS = [...FRAME_COLORS, "c2"];
+export const BaseColorEnum = z.enum(BASE_COLORS);
+export const BaseColorSetSchema = z.partialRecord(BaseColorEnum, AssetUrlSchema);
+/** Legendary-crown asset sets, grouped by variant. */
+export const CrownAssetsSchema = z.object({
+    base: ColorSetSchema.optional(),
+    ub: ColorSetSchema.optional(),
+    nickname: ColorSetSchema.optional(),
+    nicknameUb: ColorSetSchema.optional(),
+    nyxInsert: ColorSetSchema.optional(),
+    nyxInsertUb: ColorSetSchema.optional(),
+});
+/** Mask pair keyed by frame size (regular = 3-ability, tall = 4-ability). */
+const PlaneswalkerMasksSchema = z.object({
+    regular: AssetUrlSchema.optional(),
+    tall: AssetUrlSchema.optional(),
+});
+/** Planeswalker ability-icon assets. */
+export const PlaneswalkerAssetConfigSchema = z.object({
+    plus: AssetUrlSchema,
+    minus: AssetUrlSchema,
+    zero: AssetUrlSchema,
+    separator: AssetUrlSchema,
+    startingLoyalty: AssetUrlSchema,
+    /** Ability box masks. */
+    masks: PlaneswalkerMasksSchema.optional(),
+    /** Colorless-frame overlay masks (nickname banner cutout). */
+    colorlessNicknameMasks: PlaneswalkerMasksSchema.optional(),
+});
+const BannerMasksSchema = z.object({
+    right: AssetUrlSchema,
+    stripe: AssetUrlSchema,
+});
+/**
+ * Saga ability badge/divider + per-color chapter banners. Read-ahead cards use
+ * the `bannerTransform`/`bannerTransformMasks` variants. Banner masks live here
+ * (not in `masks`) because they are per-banner-variant art wired straight into
+ * the saga node, never resolved through the layout-mask path.
+ */
+export const SagaAssetConfigSchema = z.object({
+    badge: AssetUrlSchema,
+    divider: AssetUrlSchema,
+    banner: ColorSetSchema.optional(),
+    bannerTransform: ColorSetSchema.optional(),
+    bannerMasks: BannerMasksSchema.optional(),
+    bannerTransformMasks: BannerMasksSchema.optional(),
+    bannerReadAheadMasks: BannerMasksSchema.optional(),
+});
+/** The full frame-asset tree for a layout. */
+export const FrameAssetsSchema = z.object({
+    base: BaseColorSetSchema,
+    /** Planeswalker 4+-ability ("tall") variants of the base color frames. */
+    tall: ColorSetSchema.optional(),
+    land: ColorSetSchema.optional(),
+    nyx: ColorSetSchema.optional(),
+    /**
+     * Textless creature variant of the base frames — has a baked-in PT plate
+     * notch, used instead of `base` when the card has power/toughness (see
+     * `renderCardToCanvas`).
+     */
+    creature: ColorSetSchema.optional(),
+    pt: ColorSetSchema.optional(),
+    crown: CrownAssetsSchema.optional(),
+    nickname: ColorSetSchema.optional(),
+    /** Token name-plate banner, drawn over the frame in place of the normal title. */
+    tokenTitle: ColorSetSchema.optional(),
+    /** Crown black backing strip. */
+    black: AssetUrlSchema.optional(),
+    planeswalker: PlaneswalkerAssetConfigSchema.optional(),
+    saga: SagaAssetConfigSchema.optional(),
+    /** Extended-art overlay drawn on top of the masked frame. */
+    extendedOverlay: AssetUrlSchema.optional(),
+    /**
+     * Legacy single DFC icon overlaid on the crown of transform cards. Superseded
+     * by `dfcIconSet` (resolved from the card's actual `frame_effects`); kept as
+     * a fallback for any layout that hasn't shipped the full icon set.
+     */
+    dfcIcon: AssetUrlSchema.optional(),
+    /**
+     * Transform DFC icons keyed by `frame_effects` variant (e.g. "sunmoondfc",
+     * "convertdfc") — the icon actually drawn is whichever variant the card's
+     * own `frame_effects` names, so every transform card gets its correct mark
+     * (not just legendary ones, and not always the "convertdfc" mark).
+     */
+    dfcIconSet: DfcIconSetSchema.optional(),
+    /**
+     * Per-color DFC icons (modal DFC) — keyed by the *other* face's frame color,
+     * so the front face shows the back's indicator and vice versa. Used instead
+     * of the single `dfcIcon` image when the layout ships per-color icons.
+     */
+    dfcIconColorSet: ColorSetSchema.optional(),
+    /**
+     * Modal DFC "flipside" badges — small per-color badge art drawn in the
+     * bottom corner of the rules area showing the *other* face's frame color.
+     * The front face uses the badge for the back face's color, and vice versa.
+     * Keyed by frame color (w/u/b/r/g/m/a/c/l).
+     */
+    flipside: ColorSetSchema.optional(),
+    /**
+     * Crown icon drawn on Lesson cards (rendered as a Transform front face —
+     * see `getCardLayout`) in place of the usual `dfcIconSet`/`dfcIcon` mark.
+     */
+    lessonIcon: AssetUrlSchema.optional(),
+});
+/**
+ * Section masks the renderer actually reads. `rightHalf` overrides the global
+ * default (`globalMasks.rightHalf`) when a layout ships its own. The legacy
+ * `frame`/`border` mask keys are intentionally absent — nothing reads them.
+ */
+export const LayoutMasksSchema = z.object({
+    pinlines: AssetUrlSchema.optional(),
+    titleAndType: AssetUrlSchema.optional(),
+    rules: AssetUrlSchema.optional(),
+    noBorder: AssetUrlSchema.optional(),
+    legendary: AssetUrlSchema.optional(),
+    /** Legendary crown mask variant for transforming MDFC front faces — the
+     * composited top-half frame uses a different legendary crown cutout than
+     * the regular MDFC legendary mask. See `drawCardToStage.ts`. */
+    legendaryTransform: AssetUrlSchema.optional(),
+    /** No-border mask variant for transforming MDFC front faces — the
+     * composited top-half frame uses a different no-border cutout than the
+     * regular MDFC no-border mask. See `drawCardToStage.ts`. */
+    noBorderTransform: AssetUrlSchema.optional(),
+    rightHalf: AssetUrlSchema.optional(),
+    title: AssetUrlSchema.optional(),
+    type: AssetUrlSchema.optional(),
+    keyword: AssetUrlSchema.optional(),
+    /** Extended-art cutout mask applied to the combined frame. */
+    extended: AssetUrlSchema.optional(),
+    /**
+     * Half-frame cutouts for compositing two faces into one frame: the front
+     * face's frame is trimmed to its top half and composited with the back
+     * face's frame trimmed to its bottom half, so a single-face layout reads
+     * as one frame built from both faces. See `getCardLayout` and
+     * `drawCardToStage`.
+     */
+    topHalf: AssetUrlSchema.optional(),
+    bottomHalf: AssetUrlSchema.optional(),
+});

package/dist/schema/frameMeta.d.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/**
+ * The marker file that says "a frame lives in this directory".
+ *
+ * Packaging has to work both in a pnpm workspace of packages (Card Anvil's own
+ * frames) and in a flat single-package repository (the author template), so
+ * frames are found by looking for this file rather than by guessing at a
+ * directory convention.
+ */
+export declare const FRAME_META_FILENAME = "frame.meta.json";
+export declare const FrameMetaSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+    entry: z.ZodDefault<z.ZodString>;
+    export: z.ZodDefault<z.ZodString>;
+    author: z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>;
+    license: z.ZodString;
+    homepage: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+export type FrameMeta = z.infer<typeof FrameMetaSchema>;

package/dist/schema/frameMeta.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+/**
+ * The marker file that says "a frame lives in this directory".
+ *
+ * Packaging has to work both in a pnpm workspace of packages (Card Anvil's own
+ * frames) and in a flat single-package repository (the author template), so
+ * frames are found by looking for this file rather than by guessing at a
+ * directory convention.
+ */
+export const FRAME_META_FILENAME = "frame.meta.json";
+/** Reverse-DNS, e.g. `com.example.parchment`. */
+const IdSchema = z
+    .string()
+    .regex(/^[a-z0-9]+(\.[a-z0-9-]+)+$/, "must be reverse-DNS, lower case, e.g. com.example.parchment");
+/** Lower-case kebab, used for filenames. */
+const SlugSchema = z
+    .string()
+    .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, "must be lower-case kebab-case");
+export const FrameMetaSchema = z.object({
+    $schema: z.string().optional(),
+    /**
+     * Stable identity. Never changes across releases — it is what an installed
+     * frame is keyed by, and what a marketplace binds to a repository.
+     */
+    id: IdSchema,
+    /**
+     * Names the bundle file. Defaults to the directory basename, so it only
+     * needs setting when the directory is named something else (Card Anvil's
+     * `packages/frame-m15` ships as `m15`).
+     */
+    slug: SlugSchema.optional(),
+    /** Module exporting the frame, relative to this file. */
+    entry: z.string().default("./index.ts"),
+    /** Named export to read from `entry`. */
+    export: z.string().default("default"),
+    author: z.object({
+        name: z.string().min(1),
+        url: z.url().optional(),
+    }),
+    /**
+     * How the frame's art is licensed. Required because it travels into the
+     * distributable index where anyone installing the frame can read it, and
+     * nobody else can answer it for you. SPDX identifiers are preferred;
+     * `NOASSERTION` is the SPDX way to say no claim is being made.
+     */
+    license: z.string().min(1),
+    homepage: z.url().optional(),
+});

package/dist/schema/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./assetUrl.js";
+export * from "./frame.js";
+export * from "./frameAssets.js";
+export * from "./frameMeta.js";
+export * from "./layout.js";

package/dist/schema/index.js

@@ -0,0 +1,5 @@
+export * from "./assetUrl.js";
+export * from "./frame.js";
+export * from "./frameAssets.js";
+export * from "./frameMeta.js";
+export * from "./layout.js";

package/dist/schema/layout.d.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+/**
+ * Mirrors `ScryfallLayout` from `@scryfall/api-types`.
+ *
+ * Inlined as a literal on purpose: that package ships TypeScript source rather
+ * than compiled JavaScript (`"main": "index.ts"`) and exports a runtime enum,
+ * so depending on it would make this package unusable outside a bundler that
+ * transpiles `node_modules`. Card Anvil's `src/models/layout.sync.test.ts`
+ * fails if the two ever drift.
+ */
+export declare const SCRYFALL_LAYOUTS: readonly ["normal", "split", "flip", "transform", "modal_dfc", "meld", "leveler", "class", "saga", "adventure", "mutate", "prototype", "battle", "planar", "scheme", "vanguard", "token", "double_faced_token", "emblem", "augment", "host", "art_series", "reversible_card"];
+export type ScryfallLayoutName = (typeof SCRYFALL_LAYOUTS)[number];
+/**
+ * Card shapes that Scryfall does not distinguish but frames must: a
+ * planeswalker and a Case are `normal`/`class` to Scryfall, yet need their own
+ * box geometry. Crossed with every Scryfall layout to form `<layout>_<special>`.
+ */
+export declare const specialLayouts: readonly ["planeswalker", "case"];
+/**
+ * Explicit additional layouts not covered by the `specialLayouts` cross-product.
+ * `saga_transform`/`saga_transform_creature` cover a transform DFC where EITHER
+ * face is a Saga — which physical side it is on varies per card and is resolved
+ * at render time, not by separate keys.
+ */
+export declare const additionalLayouts: readonly ["saga_creature", "saga_transform", "saga_transform_creature"];
+export declare const layouts: readonly ["normal", "split", "flip", "transform", "modal_dfc", "meld", "leveler", "class", "saga", "adventure", "mutate", "prototype", "battle", "planar", "scheme", "vanguard", "token", "double_faced_token", "emblem", "augment", "host", "art_series", "reversible_card", ...("transform_planeswalker" | "transform_case" | "saga_planeswalker" | "saga_case" | "normal_planeswalker" | "normal_case" | "split_planeswalker" | "split_case" | "flip_planeswalker" | "flip_case" | "modal_dfc_planeswalker" | "modal_dfc_case" | "meld_planeswalker" | "meld_case" | "leveler_planeswalker" | "leveler_case" | "class_planeswalker" | "class_case" | "adventure_planeswalker" | "adventure_case" | "mutate_planeswalker" | "mutate_case" | "prototype_planeswalker" | "prototype_case" | "battle_planeswalker" | "battle_case" | "planar_planeswalker" | "planar_case" | "scheme_planeswalker" | "scheme_case" | "vanguard_planeswalker" | "vanguard_case" | "token_planeswalker" | "token_case" | "double_faced_token_planeswalker" | "double_faced_token_case" | "emblem_planeswalker" | "emblem_case" | "augment_planeswalker" | "augment_case" | "host_planeswalker" | "host_case" | "art_series_planeswalker" | "art_series_case" | "reversible_card_planeswalker" | "reversible_card_case")[], "saga_creature", "saga_transform", "saga_transform_creature"];
+export declare const LayoutEnum: z.ZodEnum<{
+    transform: "transform";
+    saga: "saga";
+    normal: "normal";
+    split: "split";
+    flip: "flip";
+    modal_dfc: "modal_dfc";
+    meld: "meld";
+    leveler: "leveler";
+    class: "class";
+    adventure: "adventure";
+    mutate: "mutate";
+    prototype: "prototype";
+    battle: "battle";
+    planar: "planar";
+    scheme: "scheme";
+    vanguard: "vanguard";
+    token: "token";
+    double_faced_token: "double_faced_token";
+    emblem: "emblem";
+    augment: "augment";
+    host: "host";
+    art_series: "art_series";
+    reversible_card: "reversible_card";
+    transform_planeswalker: "transform_planeswalker";
+    transform_case: "transform_case";
+    saga_planeswalker: "saga_planeswalker";
+    saga_case: "saga_case";
+    normal_planeswalker: "normal_planeswalker";
+    normal_case: "normal_case";
+    split_planeswalker: "split_planeswalker";
+    split_case: "split_case";
+    flip_planeswalker: "flip_planeswalker";
+    flip_case: "flip_case";
+    modal_dfc_planeswalker: "modal_dfc_planeswalker";
+    modal_dfc_case: "modal_dfc_case";
+    meld_planeswalker: "meld_planeswalker";
+    meld_case: "meld_case";
+    leveler_planeswalker: "leveler_planeswalker";
+    leveler_case: "leveler_case";
+    class_planeswalker: "class_planeswalker";
+    class_case: "class_case";
+    adventure_planeswalker: "adventure_planeswalker";
+    adventure_case: "adventure_case";
+    mutate_planeswalker: "mutate_planeswalker";
+    mutate_case: "mutate_case";
+    prototype_planeswalker: "prototype_planeswalker";
+    prototype_case: "prototype_case";
+    battle_planeswalker: "battle_planeswalker";
+    battle_case: "battle_case";
+    planar_planeswalker: "planar_planeswalker";
+    planar_case: "planar_case";
+    scheme_planeswalker: "scheme_planeswalker";
+    scheme_case: "scheme_case";
+    vanguard_planeswalker: "vanguard_planeswalker";
+    vanguard_case: "vanguard_case";
+    token_planeswalker: "token_planeswalker";
+    token_case: "token_case";
+    double_faced_token_planeswalker: "double_faced_token_planeswalker";
+    double_faced_token_case: "double_faced_token_case";
+    emblem_planeswalker: "emblem_planeswalker";
+    emblem_case: "emblem_case";
+    augment_planeswalker: "augment_planeswalker";
+    augment_case: "augment_case";
+    host_planeswalker: "host_planeswalker";
+    host_case: "host_case";
+    art_series_planeswalker: "art_series_planeswalker";
+    art_series_case: "art_series_case";
+    reversible_card_planeswalker: "reversible_card_planeswalker";
+    reversible_card_case: "reversible_card_case";
+    saga_creature: "saga_creature";
+    saga_transform: "saga_transform";
+    saga_transform_creature: "saga_transform_creature";
+}>;
+export type Layout = z.infer<typeof LayoutEnum>;

package/dist/schema/layout.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+/**
+ * Mirrors `ScryfallLayout` from `@scryfall/api-types`.
+ *
+ * Inlined as a literal on purpose: that package ships TypeScript source rather
+ * than compiled JavaScript (`"main": "index.ts"`) and exports a runtime enum,
+ * so depending on it would make this package unusable outside a bundler that
+ * transpiles `node_modules`. Card Anvil's `src/models/layout.sync.test.ts`
+ * fails if the two ever drift.
+ */
+export const SCRYFALL_LAYOUTS = [
+    "normal",
+    "split",
+    "flip",
+    "transform",
+    "modal_dfc",
+    "meld",
+    "leveler",
+    "class",
+    "saga",
+    "adventure",
+    "mutate",
+    "prototype",
+    "battle",
+    "planar",
+    "scheme",
+    "vanguard",
+    "token",
+    "double_faced_token",
+    "emblem",
+    "augment",
+    "host",
+    "art_series",
+    "reversible_card",
+];
+/**
+ * Card shapes that Scryfall does not distinguish but frames must: a
+ * planeswalker and a Case are `normal`/`class` to Scryfall, yet need their own
+ * box geometry. Crossed with every Scryfall layout to form `<layout>_<special>`.
+ */
+export const specialLayouts = ["planeswalker", "case"];
+const customLayouts = SCRYFALL_LAYOUTS.flatMap((layout) => specialLayouts.map((special) => `${layout}_${special}`));
+/**
+ * Explicit additional layouts not covered by the `specialLayouts` cross-product.
+ * `saga_transform`/`saga_transform_creature` cover a transform DFC where EITHER
+ * face is a Saga — which physical side it is on varies per card and is resolved
+ * at render time, not by separate keys.
+ */
+export const additionalLayouts = [
+    "saga_creature",
+    "saga_transform",
+    "saga_transform_creature",
+];
+export const layouts = [
+    ...SCRYFALL_LAYOUTS,
+    ...customLayouts,
+    ...additionalLayouts,
+];
+export const LayoutEnum = z.enum(layouts);

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@cardanvil/frame-kit",
+  "version": "0.2.0",
+  "description": "The contract Card Anvil frames are authored against: schemas, types, authoring helpers, and the distributable manifest format.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Card-Anvil/frames.git",
+    "directory": "packages/frame-kit"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "default": "./dist/manifest/index.js"
+    },
+    "./packaging": {
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "vite": "^6 || ^7",
+    "zod": "^4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "@types/yazl": "^3.3.1",
+    "vite": "^7.3.6"
+  },
+  "dependencies": {
+    "yazl": "^3.3.1"
+  },
+  "bin": {
+    "frame-kit": "./dist/cli/main.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node dist/cli/emitSchemas.js"
+  }
+}