@cardanvil/frame-kit 0.6.0 → 0.7.0

package/dist/schema/layout.d.ts

@@ -12,8 +12,12 @@ export declare const SCRYFALL_LAYOUTS: readonly ["normal", "split", "flip", "tra
 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>`.
+ * planeswalker is `normal` to Scryfall, yet needs its own box geometry. Crossed
+ * with every Scryfall layout to form `<layout>_<special>`.
+ *
+ * `case` is here for compatibility only. Scryfall files a Case under a `case`
+ * layout of its own (see `additionalLayouts`), and Card Anvil keys every Case
+ * card there, so a `<layout>_case` key is never looked up.
  */
 export declare const specialLayouts: readonly ["planeswalker", "case"];
 /**
@@ -21,9 +25,26 @@ export declare const specialLayouts: readonly ["planeswalker", "case"];
  * `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.
+ *
+ * `omen` and `prepare` join `adventure` as the layouts that print a second
+ * spell inset in the text box (see the `inset*` boxes in `frame.ts`). Scryfall
+ * files Omen cards under `adventure`, told apart only by the inset's type
+ * line, but their frame art differs, so frames key them separately. `prepare`
+ * is a layout Scryfall does return; it is listed here rather than in
+ * `SCRYFALL_LAYOUTS` because `@scryfall/api-types` predates it, and that list
+ * has to match the package.
+ *
+ * `aftermath` is to `split` what `omen` is to `adventure`: Scryfall files an
+ * aftermath card under `split`, told apart only by its Aftermath keyword, but
+ * it prints its first half upright and its second sideways where a split card
+ * turns both.
+ *
+ * `case` is a layout Scryfall returns for Case cards (e.g. Case of the Burning
+ * Masks), listed here rather than in `SCRYFALL_LAYOUTS` for the reason
+ * `prepare` is: `@scryfall/api-types` predates it.
  */
-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 additionalLayouts: readonly ["saga_creature", "saga_transform", "saga_transform_creature", "omen", "prepare", "aftermath", "case"];
+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", "omen", "prepare", "aftermath", "case"];
 export declare const LayoutEnum: z.ZodEnum<{
     transform: "transform";
     saga: "saga";
@@ -48,6 +69,7 @@ export declare const LayoutEnum: z.ZodEnum<{
     host: "host";
     art_series: "art_series";
     reversible_card: "reversible_card";
+    case: "case";
     transform_planeswalker: "transform_planeswalker";
     transform_case: "transform_case";
     saga_planeswalker: "saga_planeswalker";
@@ -97,5 +119,8 @@ export declare const LayoutEnum: z.ZodEnum<{
     saga_creature: "saga_creature";
     saga_transform: "saga_transform";
     saga_transform_creature: "saga_transform_creature";
+    omen: "omen";
+    prepare: "prepare";
+    aftermath: "aftermath";
 }>;
 export type Layout = z.infer<typeof LayoutEnum>;

package/dist/schema/layout.js

@@ -35,8 +35,12 @@ export const SCRYFALL_LAYOUTS = [
 ];
 /**
  * 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>`.
+ * planeswalker is `normal` to Scryfall, yet needs its own box geometry. Crossed
+ * with every Scryfall layout to form `<layout>_<special>`.
+ *
+ * `case` is here for compatibility only. Scryfall files a Case under a `case`
+ * layout of its own (see `additionalLayouts`), and Card Anvil keys every Case
+ * card there, so a `<layout>_case` key is never looked up.
  */
 export const specialLayouts = ["planeswalker", "case"];
 const customLayouts = SCRYFALL_LAYOUTS.flatMap((layout) => specialLayouts.map((special) => `${layout}_${special}`));
@@ -45,11 +49,32 @@ const customLayouts = SCRYFALL_LAYOUTS.flatMap((layout) => specialLayouts.map((s
  * `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.
+ *
+ * `omen` and `prepare` join `adventure` as the layouts that print a second
+ * spell inset in the text box (see the `inset*` boxes in `frame.ts`). Scryfall
+ * files Omen cards under `adventure`, told apart only by the inset's type
+ * line, but their frame art differs, so frames key them separately. `prepare`
+ * is a layout Scryfall does return; it is listed here rather than in
+ * `SCRYFALL_LAYOUTS` because `@scryfall/api-types` predates it, and that list
+ * has to match the package.
+ *
+ * `aftermath` is to `split` what `omen` is to `adventure`: Scryfall files an
+ * aftermath card under `split`, told apart only by its Aftermath keyword, but
+ * it prints its first half upright and its second sideways where a split card
+ * turns both.
+ *
+ * `case` is a layout Scryfall returns for Case cards (e.g. Case of the Burning
+ * Masks), listed here rather than in `SCRYFALL_LAYOUTS` for the reason
+ * `prepare` is: `@scryfall/api-types` predates it.
  */
 export const additionalLayouts = [
     "saga_creature",
     "saga_transform",
     "saga_transform_creature",
+    "omen",
+    "prepare",
+    "aftermath",
+    "case",
 ];
 export const layouts = [
     ...SCRYFALL_LAYOUTS,

package/dist/schema/paint.d.ts

@@ -0,0 +1,202 @@
+import { z } from "zod";
+/** A color written `#rrggbb`. */
+export declare const HexColorSchema: z.ZodString;
+/**
+ * A color taken from the card: its pinline colors, each looked up in
+ * `palette`.
+ *
+ * A card with one pinline color paints that color. A two-color card paints
+ * its two colors in their printed order (`WU`, `GW`…), and a three-color card
+ * its three (`GWU`, `URW`…) — but only up to `maxParts`; a card with more
+ * colors than that paints the palette's gold (`m`). Artifact, colorless, land
+ * and vehicle pinlines paint `a`, `c`, `l` and `v`. A color the palette leaves
+ * out paints nothing.
+ */
+export declare const CardColorsSchema: z.ZodObject<{
+    palette: z.ZodRecord<z.ZodEnum<{
+        a: "a";
+        w: "w";
+        u: "u";
+        b: "b";
+        r: "r";
+        g: "g";
+        m: "m";
+        c: "c";
+        l: "l";
+        v: "v";
+    }> & z.core.$partial, z.ZodString>;
+    maxParts: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CardColors = z.infer<typeof CardColorsSchema>;
+/** One opacity along a gradient: `opacity` (0–1) at `at` (0 start, 1 end). */
+export declare const OpacityStopSchema: z.ZodObject<{
+    at: z.ZodNumber;
+    opacity: z.ZodNumber;
+}, z.core.$strip>;
+export type OpacityStop = z.infer<typeof OpacityStopSchema>;
+/**
+ * The boxes a `rulesSlide` can move, and a gradient can be anchored to: the
+ * header above the rules text.
+ */
+export declare const SlidingBoxEnum: z.ZodEnum<{
+    type: "type";
+    title: "title";
+    mana: "mana";
+    setSymbol: "setSymbol";
+}>;
+export type SlidingBox = z.infer<typeof SlidingBoxEnum>;
+/**
+ * A rectangle painted on the sheet over the art and under the text, its
+ * opacity changing along `direction` by `opacity`, which needs at least two
+ * stops. Drawn in the order listed, above the frame art.
+ *
+ * `color` is one color, or the card's: for those, the rectangle is split
+ * along `direction` into one equal part per color, blended over `blend` px
+ * where two meet.
+ */
+export declare const GradientSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    direction: z.ZodOptional<z.ZodEnum<{
+        vertical: "vertical";
+        horizontal: "horizontal";
+    }>>;
+    color: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        palette: z.ZodRecord<z.ZodEnum<{
+            a: "a";
+            w: "w";
+            u: "u";
+            b: "b";
+            r: "r";
+            g: "g";
+            m: "m";
+            c: "c";
+            l: "l";
+            v: "v";
+        }> & z.core.$partial, z.ZodString>;
+        maxParts: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>;
+    opacity: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        at: z.ZodNumber;
+        opacity: z.ZodNumber;
+    }, z.core.$strip>>>;
+    anchor: z.ZodOptional<z.ZodEnum<{
+        type: "type";
+        title: "title";
+        mana: "mana";
+        setSymbol: "setSymbol";
+    }>>;
+    slides: z.ZodOptional<z.ZodBoolean>;
+    when: z.ZodOptional<z.ZodObject<{
+        border: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            default: "default";
+            light: "light";
+            dark: "dark";
+            none: "none";
+        }>, z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+            default: "default";
+            light: "light";
+            dark: "dark";
+            none: "none";
+        }>>>]>>;
+        settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString, z.ZodNumber]>>>;
+        frameColor: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            a: "a";
+            w: "w";
+            u: "u";
+            b: "b";
+            r: "r";
+            g: "g";
+            m: "m";
+            c: "c";
+            l: "l";
+            v: "v";
+        }>, z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+            a: "a";
+            w: "w";
+            u: "u";
+            b: "b";
+            r: "r";
+            g: "g";
+            m: "m";
+            c: "c";
+            l: "l";
+            v: "v";
+        }>>>]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Gradient = z.infer<typeof GradientSchema>;
+/**
+ * An image whose own color is replaced, keeping its alpha — a shape the frame
+ * ships once and paints per card. Drawn at its own size unless given one.
+ */
+export declare const TintedImageSchema: z.ZodObject<{
+    src: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    color: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        palette: z.ZodRecord<z.ZodEnum<{
+            a: "a";
+            w: "w";
+            u: "u";
+            b: "b";
+            r: "r";
+            g: "g";
+            m: "m";
+            c: "c";
+            l: "l";
+            v: "v";
+        }> & z.core.$partial, z.ZodString>;
+        maxParts: z.ZodOptional<z.ZodNumber>;
+        part: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>]>;
+    showWith: z.ZodOptional<z.ZodLiteral<"powerToughness">>;
+    ptSlot: z.ZodOptional<z.ZodEnum<{
+        power: "power";
+        toughness: "toughness";
+    }>>;
+    slides: z.ZodOptional<z.ZodBoolean>;
+    when: z.ZodOptional<z.ZodObject<{
+        border: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            default: "default";
+            light: "light";
+            dark: "dark";
+            none: "none";
+        }>, z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+            default: "default";
+            light: "light";
+            dark: "dark";
+            none: "none";
+        }>>>]>>;
+        settings: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodBoolean, z.ZodString, z.ZodNumber]>>>;
+        frameColor: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+            a: "a";
+            w: "w";
+            u: "u";
+            b: "b";
+            r: "r";
+            g: "g";
+            m: "m";
+            c: "c";
+            l: "l";
+            v: "v";
+        }>, z.ZodReadonly<z.ZodArray<z.ZodEnum<{
+            a: "a";
+            w: "w";
+            u: "u";
+            b: "b";
+            r: "r";
+            g: "g";
+            m: "m";
+            c: "c";
+            l: "l";
+            v: "v";
+        }>>>]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TintedImage = z.infer<typeof TintedImageSchema>;

package/dist/schema/paint.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { AssetUrlSchema } from "./assetUrl.js";
+import { RenderConditionSchema } from "./condition.js";
+import { FrameColorEnum } from "./frameAssets.js";
+/** A color written `#rrggbb`. */
+export const HexColorSchema = z
+    .string()
+    .regex(/^#[0-9a-fA-F]{6}$/, "expected a color written #rrggbb");
+/**
+ * A color taken from the card: its pinline colors, each looked up in
+ * `palette`.
+ *
+ * A card with one pinline color paints that color. A two-color card paints
+ * its two colors in their printed order (`WU`, `GW`…), and a three-color card
+ * its three (`GWU`, `URW`…) — but only up to `maxParts`; a card with more
+ * colors than that paints the palette's gold (`m`). Artifact, colorless, land
+ * and vehicle pinlines paint `a`, `c`, `l` and `v`. A color the palette leaves
+ * out paints nothing.
+ */
+export const CardColorsSchema = z.object({
+    palette: z.partialRecord(FrameColorEnum, HexColorSchema),
+    /**
+     * The most colors painted side by side, 1–3. Defaults to 1, where any
+     * multicolor card is gold.
+     */
+    maxParts: z.number().int().min(1).max(3).optional(),
+});
+/** One opacity along a gradient: `opacity` (0–1) at `at` (0 start, 1 end). */
+export const OpacityStopSchema = z.object({
+    at: z.number().min(0).max(1),
+    opacity: z.number().min(0).max(1),
+});
+/**
+ * The boxes a `rulesSlide` can move, and a gradient can be anchored to: the
+ * header above the rules text.
+ */
+export const SlidingBoxEnum = z.enum(["mana", "title", "type", "setSymbol"]);
+/**
+ * A rectangle painted on the sheet over the art and under the text, its
+ * opacity changing along `direction` by `opacity`, which needs at least two
+ * stops. Drawn in the order listed, above the frame art.
+ *
+ * `color` is one color, or the card's: for those, the rectangle is split
+ * along `direction` into one equal part per color, blended over `blend` px
+ * where two meet.
+ */
+export const GradientSchema = z.object({
+    x: z.number(),
+    y: z.number(),
+    width: z.number(),
+    height: z.number(),
+    /** Which way `opacity` runs: down the sheet, or across it. Defaults to vertical. */
+    direction: z.enum(["vertical", "horizontal"]).optional(),
+    color: z.union([
+        HexColorSchema,
+        CardColorsSchema.extend({
+            /** Px over which two of the card's colors blend into each other. */
+            blend: z.number().nonnegative().optional(),
+        }),
+    ]),
+    opacity: z.array(OpacityStopSchema).min(2).readonly(),
+    /**
+     * The box the gradient moves with. Its `y` is then measured from that box's
+     * top in the boxes the card is drawn with — whichever set the layout picks
+     * for it (a planeswalker's by how many abilities it has) and wherever a
+     * `rulesSlide` has moved them. Takes the place of `slides`, which it
+     * ignores.
+     */
+    anchor: SlidingBoxEnum.optional(),
+    /** Moves with the boxes when the layout's `rulesSlide` moves them. */
+    slides: z.boolean().optional(),
+    /** Drawn only on a render where this holds, e.g. a template setting's value. */
+    when: RenderConditionSchema.optional(),
+});
+/**
+ * An image whose own color is replaced, keeping its alpha — a shape the frame
+ * ships once and paints per card. Drawn at its own size unless given one.
+ */
+export const TintedImageSchema = z.object({
+    src: AssetUrlSchema,
+    x: z.number(),
+    y: z.number(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    /**
+     * One color, or one of the card's (see `CardColorsSchema`): `part` 0 is
+     * the first, and a card with fewer colors paints its last.
+     */
+    color: z.union([
+        HexColorSchema,
+        CardColorsSchema.extend({ part: z.number().int().min(0).optional() }),
+    ]),
+    /** Drawn only on a card with power and toughness, as the P/T is. */
+    showWith: z.literal("powerToughness").optional(),
+    /**
+     * Placed beside a number of the layout's `powerToughnessRow`: the image's
+     * right edge goes the row's `gap` left of that number, so it moves with
+     * the number as it widens, and `x` only nudges it from there (usually 0).
+     * Without a row, `x` places it as usual.
+     */
+    ptSlot: z.enum(["power", "toughness"]).optional(),
+    /** Moves with the boxes when the layout's `rulesSlide` moves them. */
+    slides: z.boolean().optional(),
+    /**
+     * Drawn only on a render where this holds — a frame offering two sets of
+     * symbols lists both, each under the value of the setting that picks it.
+     */
+    when: RenderConditionSchema.optional(),
+});