@cardanvil/frame-kit 0.6.0 → 0.7.0

package/dist/manifest/contract.js

@@ -13,12 +13,57 @@ import { FrameSchema } from "../schema/frame.js";
  *   render with reduced fidelity.
  *
  * Version history:
+ * - 1.13: added the optional `fonts` a frame ships; the optional `gradients`,
+ *   `tintedImages`, `rulesSlide` and `manaSymbols` on a layout; the optional
+ *   `power` and `toughness` text boxes; the optional `shadowBlur` on text
+ *   boxes; the optional `frameColor` condition on text box `overrides`; and
+ *   the optional `when` on gradients and tinted images, the same conditions
+ *   as `overrides`, so a template setting can pick which are drawn; and the
+ *   optional `powerToughnessRow` on a layout, with `ptSlot` on the tinted
+ *   images it places; the optional planeswalker `abilityDivider`, a
+ *   gradient painted where each two abilities meet; and the optional
+ *   `anchor` on gradients, the box one moves with.
+ *   A layout's `base` frame art may now be empty, for a frame with none.
+ * - 1.12: added the optional planeswalker knobs `abilityFill`,
+ *   `abilityFillSize`, `minFontSize`, `lineHeightRatio`, `badgeSlotHeight` and
+ *   `loyaltyReserve`, which space and size abilities laid out as a column of
+ *   sections, and `separatorOffsetY`,
+ *   which places the separators between their bands; `topPadding`,
+ *   `bottomPadding` and `textFillThreshold` are no longer read.
+ * - 1.11: added the optional `sectionDividers` on a layout, fixed dividers
+ *   drawn with `sectionDivider`; and an `alternateLayouts` entry can now be
+ *   named by a layout's own select setting as well as by `frameVariant`.
+ * - 1.10: added the optional `sectionDivider` frame asset, drawn between the
+ *   sections of a Case's or Class's column.
+ * - 1.9: added the optional `adventureRules`, `adventureRulesRight`,
+ *   `rulesRight` and `wings` layout masks, colouring the two pages and the
+ *   page edges of a storybook Adventure's text box on their own.
+ * - 1.8: added the optional `fullBorder` frame asset, border art drawn under
+ *   the base frame while `useFullBorder` is on; the optional
+ *   `outlineColor`/`outlineWidth` on the set symbol box; the optional
+ *   `tallMasks`, the planeswalker tall frame's own masks; and the optional
+ *   planeswalker knobs `abilityBacking` and the loyalty badge and cost
+ *   offsets. The planeswalker `separator` asset became optional, so a frame
+ *   that leaves it out needs a 1.8 loader.
+ * - 1.7: added the optional `firstArt` on a box set and `art` on a second
+ *   face's set: the windows a card's two arts go in once it has a second one.
+ * - 1.6: added the optional `rotation` on a box set, for text and art read
+ *   with the card turned; the optional `secondFaceBoxes` set, for a second
+ *   face printed on the same side as the first; the optional `defense` and
+ *   `fuse` text boxes; and the `aftermath` layout.
+ * - 1.5: added the optional `insetTitle`, `insetMana`, `insetType` and
+ *   `insetRules` text boxes for the spell inset in an Adventure, Omen or
+ *   Prepare card's text box, and the `omen` and `prepare` layouts.
+ * - 1.4: added the optional `overrides` on text boxes, conditional restyles
+ *   matched against the border settings and template settings. Also the
+ *   optional `shadowOffsetX`/`shadowOffsetY` on text boxes,
+ *   `lines` on the collector info box, and the `dividerBar*` frame assets.
  * - 1.3: added the optional `border` layout mask, isolating the outer
  *   border ring's own shape so it can be recolored.
  * - 1.2: added the optional `mask` asset URL on text boxes (shaped text).
  * - 1.1: added the optional `license` field on the manifest.
  */
-export const CONTRACT_VERSION = "1.3";
+export const CONTRACT_VERSION = "1.13";
 /** The only manifest kind any loader understands today. */
 export const DECLARATIVE_KIND = "declarative";
 export const AssetEntrySchema = z.object({

package/dist/manifest/testFrame.js

@@ -38,6 +38,15 @@ export const testFrame = {
                         color: "white",
                         outlineColor: "black",
                         fontFamily: "Beleren",
+                        overrides: [
+                            {
+                                when: {
+                                    border: ["light", "none"],
+                                    settings: { style: "modern" },
+                                },
+                                style: { color: "black" },
+                            },
+                        ],
                     },
                     type: { x: 0, y: 0, width: 10, height: 10, fontSize: 12 },
                     setSymbol: { x: 0, y: 0, width: 10, height: 10 },

package/dist/schema/collectorInfo.d.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+/**
+ * A value the collector line can print. Each resolves from the card and the
+ * user's field settings at render time, except `separator` and `artistSymbol`,
+ * which are glyphs.
+ */
+export declare const CollectorInfoElementTypeSchema: z.ZodEnum<{
+    rarity: "rarity";
+    cardNumber: "cardNumber";
+    creatorName: "creatorName";
+    setCode: "setCode";
+    separator: "separator";
+    language: "language";
+    artistSymbol: "artistSymbol";
+    artist: "artist";
+}>;
+export type CollectorInfoElementType = z.infer<typeof CollectorInfoElementTypeSchema>;
+export declare const CollectorInfoElementSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        rarity: "rarity";
+        cardNumber: "cardNumber";
+        creatorName: "creatorName";
+        setCode: "setCode";
+        separator: "separator";
+        language: "language";
+        artistSymbol: "artistSymbol";
+        artist: "artist";
+    }>;
+    useManaFont: z.ZodOptional<z.ZodBoolean>;
+    manaSymbol: z.ZodOptional<z.ZodString>;
+    fontSizeMultiplier: z.ZodOptional<z.ZodNumber>;
+    fontSizeMultiplierDot: z.ZodOptional<z.ZodNumber>;
+    fontSizeMultiplierStar: z.ZodOptional<z.ZodNumber>;
+    yOffset: z.ZodOptional<z.ZodNumber>;
+    yOffsetDot: z.ZodOptional<z.ZodNumber>;
+    yOffsetStar: z.ZodOptional<z.ZodNumber>;
+    spacingAfter: z.ZodOptional<z.ZodNumber>;
+    letterSpacing: z.ZodOptional<z.ZodNumber>;
+    minXFromElement: z.ZodOptional<z.ZodEnum<{
+        rarity: "rarity";
+        cardNumber: "cardNumber";
+        creatorName: "creatorName";
+        setCode: "setCode";
+        separator: "separator";
+        language: "language";
+        artistSymbol: "artistSymbol";
+        artist: "artist";
+    }>>;
+    prefix: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CollectorInfoElement = z.infer<typeof CollectorInfoElementSchema>;
+/** One line of the collector box: elements drawn left to right. */
+export declare const CollectorInfoLineSchema: z.ZodObject<{
+    elements: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            rarity: "rarity";
+            cardNumber: "cardNumber";
+            creatorName: "creatorName";
+            setCode: "setCode";
+            separator: "separator";
+            language: "language";
+            artistSymbol: "artistSymbol";
+            artist: "artist";
+        }>;
+        useManaFont: z.ZodOptional<z.ZodBoolean>;
+        manaSymbol: z.ZodOptional<z.ZodString>;
+        fontSizeMultiplier: z.ZodOptional<z.ZodNumber>;
+        fontSizeMultiplierDot: z.ZodOptional<z.ZodNumber>;
+        fontSizeMultiplierStar: z.ZodOptional<z.ZodNumber>;
+        yOffset: z.ZodOptional<z.ZodNumber>;
+        yOffsetDot: z.ZodOptional<z.ZodNumber>;
+        yOffsetStar: z.ZodOptional<z.ZodNumber>;
+        spacingAfter: z.ZodOptional<z.ZodNumber>;
+        letterSpacing: z.ZodOptional<z.ZodNumber>;
+        minXFromElement: z.ZodOptional<z.ZodEnum<{
+            rarity: "rarity";
+            cardNumber: "cardNumber";
+            creatorName: "creatorName";
+            setCode: "setCode";
+            separator: "separator";
+            language: "language";
+            artistSymbol: "artistSymbol";
+            artist: "artist";
+        }>>;
+        prefix: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    spacing: z.ZodOptional<z.ZodNumber>;
+    align: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        center: "center";
+    }>>;
+    fontSizeMultiplier: z.ZodOptional<z.ZodNumber>;
+    fontFamily: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CollectorInfoLine = z.infer<typeof CollectorInfoLineSchema>;

package/dist/schema/collectorInfo.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+/**
+ * A value the collector line can print. Each resolves from the card and the
+ * user's field settings at render time, except `separator` and `artistSymbol`,
+ * which are glyphs.
+ */
+export const CollectorInfoElementTypeSchema = z.enum([
+    "rarity",
+    "cardNumber",
+    "creatorName",
+    "setCode",
+    /** Dot or star, per the user's separator setting (from the mana font). */
+    "separator",
+    "language",
+    /** The paintbrush glyph (from the mana font). */
+    "artistSymbol",
+    "artist",
+]);
+export const CollectorInfoElementSchema = z.object({
+    type: CollectorInfoElementTypeSchema,
+    /** Draw in Manadings-Regular (for `separator` and `artistSymbol`). */
+    useManaFont: z.boolean().optional(),
+    /** The mana-font character to draw, e.g. `"a"` for the artist symbol. */
+    manaSymbol: z.string().optional(),
+    /** Multiplier on the box's font size. Default 1.0. */
+    fontSizeMultiplier: z.number().optional(),
+    /** `fontSizeMultiplier` for the dot separator only. */
+    fontSizeMultiplierDot: z.number().optional(),
+    /** `fontSizeMultiplier` for the star separator only. */
+    fontSizeMultiplierStar: z.number().optional(),
+    /** Vertical offset in px, positive down. */
+    yOffset: z.number().optional(),
+    /** `yOffset` for the dot separator only. */
+    yOffsetDot: z.number().optional(),
+    /** `yOffset` for the star separator only. */
+    yOffsetStar: z.number().optional(),
+    /** Space after this element in px, overriding the line's `spacing`. */
+    spacingAfter: z.number().optional(),
+    /**
+     * Per-element letter spacing in px, overriding the collector box's
+     * `letterSpacing` for this element's characters (e.g. tighten the artist
+     * name while the rarity/number keep the box tracking). Absolute px like
+     * `spacingAfter` — it does not scale with `fontSizeMultiplier`. Set `0` to
+     * render this element untracked while the box has tracking.
+     */
+    letterSpacing: z.number().optional(),
+    /**
+     * When set, this element's x position is never less than the x position of
+     * the referenced element type on another line. If the elements before this
+     * one on the same line already extend past that position, this element
+     * follows naturally. Used to align the creator name with the artist symbol.
+     */
+    minXFromElement: CollectorInfoElementTypeSchema.optional(),
+    /**
+     * Literal text prepended to the resolved value (e.g. "Illus. " before the
+     * artist name). Omitted entirely if the value is empty.
+     */
+    prefix: z.string().optional(),
+});
+/** One line of the collector box: elements drawn left to right. */
+export const CollectorInfoLineSchema = z.object({
+    elements: z.array(CollectorInfoElementSchema).readonly(),
+    /** Space between elements in px. Default 10. */
+    spacing: z.number().optional(),
+    /**
+     * Horizontal alignment within the box's width. Defaults to "left" (the
+     * elements flow left-to-right from the box's left edge).
+     */
+    align: z.enum(["left", "center"]).optional(),
+    /**
+     * Multiplier applied to every element's font size on this line, stacking
+     * with each element's own `fontSizeMultiplier`. Default 1.0.
+     */
+    fontSizeMultiplier: z.number().optional(),
+    /**
+     * Overrides the font family for every text element on this line (the
+     * artist/creator-name/Gotham default otherwise used per element type).
+     */
+    fontFamily: z.string().optional(),
+});

package/dist/schema/condition.d.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+/**
+ * The frame's outer border as the renderer is about to draw it — what a
+ * `RenderCondition` matches on through `border`:
+ *
+ * - `"default"`: the frame's own border art, untouched by any border setting.
+ * - `"light"` / `"dark"`: a user border color recolors the ring, because the
+ *   layout ships a `border` mask (or `borderFull`, under `useFullBorder`).
+ *   `"light"` when black text reads better on the chosen color (WCAG
+ *   contrast), `"dark"` when white does.
+ * - `"none"`: "No Border" is on and the layout ships a `noBorder` mask, so the
+ *   ring is cut away and whatever sat on it now sits over the art.
+ *
+ * Only a layout with those masks ever leaves `"default"`, so a condition on
+ * any other state never fires for a frame whose border cannot be recolored or
+ * removed.
+ */
+export declare const BorderStateSchema: z.ZodEnum<{
+    default: "default";
+    light: "light";
+    dark: "dark";
+    none: "none";
+}>;
+export type BorderState = z.infer<typeof BorderStateSchema>;
+/**
+ * What must hold for one render for something conditional to apply: a text
+ * box's `overrides`, a gradient or a tinted image. Every condition named must
+ * hold; a condition left out matches anything.
+ */
+export declare const RenderConditionSchema: 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>;
+export type RenderCondition = z.infer<typeof RenderConditionSchema>;

package/dist/schema/condition.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+import { FrameColorEnum } from "./frameAssets.js";
+/**
+ * The frame's outer border as the renderer is about to draw it — what a
+ * `RenderCondition` matches on through `border`:
+ *
+ * - `"default"`: the frame's own border art, untouched by any border setting.
+ * - `"light"` / `"dark"`: a user border color recolors the ring, because the
+ *   layout ships a `border` mask (or `borderFull`, under `useFullBorder`).
+ *   `"light"` when black text reads better on the chosen color (WCAG
+ *   contrast), `"dark"` when white does.
+ * - `"none"`: "No Border" is on and the layout ships a `noBorder` mask, so the
+ *   ring is cut away and whatever sat on it now sits over the art.
+ *
+ * Only a layout with those masks ever leaves `"default"`, so a condition on
+ * any other state never fires for a frame whose border cannot be recolored or
+ * removed.
+ */
+export const BorderStateSchema = z.enum(["default", "light", "dark", "none"]);
+/**
+ * What must hold for one render for something conditional to apply: a text
+ * box's `overrides`, a gradient or a tinted image. Every condition named must
+ * hold; a condition left out matches anything.
+ */
+export const RenderConditionSchema = z.object({
+    /** The border state to match; an array matches any of its states. */
+    border: z
+        .union([BorderStateSchema, z.array(BorderStateSchema).readonly()])
+        .optional(),
+    /**
+     * Template settings that must hold, each compared with `===` against the
+     * value in effect for the layout — frame- and layout-level settings
+     * merged, defaults included. E.g. `{ useFullBorder: true }`.
+     */
+    settings: z
+        .record(z.string(), z.union([z.boolean(), z.string(), z.number()]))
+        .optional(),
+    /**
+     * The card's frame color — its background, the color its base frame is
+     * picked by: `w`/`u`/`b`/`r`/`g` for one color, `m` for gold and
+     * two-color hybrids, `a`, `c`, `l` or `v` for artifacts, colorless cards,
+     * lands and vehicles. An array matches any of its colors.
+     */
+    frameColor: z
+        .union([FrameColorEnum, z.array(FrameColorEnum).readonly()])
+        .optional(),
+});