@cardanvil/frame-kit 0.5.0 → 0.7.0

package/dist/layout/decorations.d.ts

@@ -0,0 +1,73 @@
+import type { FrameAssets, FrameColor } from "../schema/frameAssets.js";
+import { type FrameDetails } from "./frameLayers.js";
+/**
+ * The type-line facts the decoration colours turn on.
+ *
+ * A `CardShape` satisfies this structurally, and so does a card the app has
+ * already read a type line from.
+ */
+export interface DecorationFacts {
+    readonly isLand?: boolean;
+    readonly isArtifact?: boolean;
+    readonly isVehicle?: boolean;
+}
+/** One colour, or the two halves of a two-colour banner. */
+export type BannerColors = FrameColor | [FrameColor, FrameColor];
+/**
+ * The colour a card's banners take.
+ *
+ * Driven by the resolved identity rather than the background, so a crown, a
+ * nickname plate and a PT box on the same card always agree with each other
+ * and with the pinlines.
+ */
+export declare function identityColors(details: FrameDetails, facts?: DecorationFacts): BannerColors;
+/** Legendary crown colour(s). */
+export declare function crownColors(details: FrameDetails, facts?: DecorationFacts): BannerColors;
+/** Nickname banner colour(s). */
+export declare function nicknameColors(details: FrameDetails, facts?: DecorationFacts): BannerColors;
+/**
+ * PT box colour.
+ *
+ * Only a true two-colour hybrid takes the colourless box. A card built from
+ * monocoloured-hybrid pips in three or more colours is an ordinary gold card
+ * and must resolve by identity length instead.
+ */
+export declare function ptBoxColor(details: FrameDetails, facts?: DecorationFacts): FrameColor;
+/** Combined crown + nickname banner; the UB variant falls back to the plain one. */
+export declare function resolveCrownNicknameAsset(assets: FrameAssets, color: FrameColor, useUBCrowns: boolean): string | undefined;
+/**
+ * Legendary crown art.
+ *
+ * A nicknamed card prefers the combined crown+nickname asset, and falls back
+ * to the plain crown when a frame does not ship one.
+ */
+export declare function resolveCrownAsset(assets: FrameAssets, color: FrameColor, opts: {
+    nickname: boolean;
+    useUBCrowns: boolean;
+}): string | undefined;
+export declare function resolveNicknameAsset(assets: FrameAssets, color: FrameColor): string | undefined;
+export declare function resolvePtBoxAsset(assets: FrameAssets, color: FrameColor): string | undefined;
+export declare function resolveNyxInsertAsset(assets: FrameAssets, color: FrameColor, useUBCrowns?: boolean): string | undefined;
+/** What a card is, for deciding which banners it gets. */
+export interface DecorationCard {
+    readonly isLegendary?: boolean;
+    /** The nickname text; a card has a nickname when this is non-empty. */
+    readonly nickname?: string;
+    readonly power?: string;
+    readonly toughness?: string;
+}
+export interface DecorationState {
+    readonly crown: boolean;
+    /** The bar behind the crown, drawn on the same condition. */
+    readonly crownBlackBar: boolean;
+    readonly nickname: boolean;
+    readonly ptBox: boolean;
+}
+/**
+ * Which banners a card draws.
+ *
+ * Mirrors the renderer's conditions: crowns are legendary-only, the nickname
+ * plate needs nickname text, and the PT box needs *both* a power and a
+ * toughness — a card with only one is not a creature and gets no plate.
+ */
+export declare function decorationsFor(card: DecorationCard): DecorationState;

package/dist/layout/decorations.js

@@ -0,0 +1,104 @@
+import { splitTwoColor } from "./frameLayers.js";
+/**
+ * The colour a card's banners take.
+ *
+ * Driven by the resolved identity rather than the background, so a crown, a
+ * nickname plate and a PT box on the same card always agree with each other
+ * and with the pinlines.
+ */
+export function identityColors(details, facts = {}) {
+    const split = splitTwoColor(details.identity);
+    if (split) {
+        return split;
+    }
+    if (details.identity.length === 1) {
+        return details.identity.toLowerCase();
+    }
+    if (details.identity.length > 1) {
+        return "m";
+    }
+    // No identity: a land takes the land token so its banners match its land
+    // pinlines, and a colourless artifact the artifact token so they match its
+    // artifact pinlines; anything else stays colourless.
+    if (facts.isLand === true) {
+        return "l";
+    }
+    return facts.isArtifact === true ? "a" : "c";
+}
+/** Legendary crown colour(s). */
+export function crownColors(details, facts = {}) {
+    return identityColors(details, facts);
+}
+/** Nickname banner colour(s). */
+export function nicknameColors(details, facts = {}) {
+    return identityColors(details, facts);
+}
+/**
+ * PT box colour.
+ *
+ * Only a true two-colour hybrid takes the colourless box. A card built from
+ * monocoloured-hybrid pips in three or more colours is an ordinary gold card
+ * and must resolve by identity length instead.
+ */
+export function ptBoxColor(details, facts = {}) {
+    if (facts.isVehicle === true) {
+        return "v"; // vehicles use the dedicated plate whatever their colour
+    }
+    if (details.isHybrid) {
+        return "c";
+    }
+    if (details.identity.length === 1) {
+        return details.identity.toLowerCase();
+    }
+    if (details.identity.length > 1) {
+        return "m";
+    }
+    return facts.isArtifact === true ? "a" : "c";
+}
+/** Combined crown + nickname banner; the UB variant falls back to the plain one. */
+export function resolveCrownNicknameAsset(assets, color, useUBCrowns) {
+    return ((useUBCrowns ? assets.crown?.nicknameUb?.[color] : undefined) ??
+        assets.crown?.nickname?.[color]);
+}
+/**
+ * Legendary crown art.
+ *
+ * A nicknamed card prefers the combined crown+nickname asset, and falls back
+ * to the plain crown when a frame does not ship one.
+ */
+export function resolveCrownAsset(assets, color, opts) {
+    if (opts.nickname) {
+        const combined = resolveCrownNicknameAsset(assets, color, opts.useUBCrowns);
+        if (combined !== undefined) {
+            return combined;
+        }
+    }
+    return ((opts.useUBCrowns ? assets.crown?.ub?.[color] : undefined) ??
+        assets.crown?.base?.[color]);
+}
+export function resolveNicknameAsset(assets, color) {
+    return assets.nickname?.[color];
+}
+export function resolvePtBoxAsset(assets, color) {
+    return assets.pt?.[color];
+}
+export function resolveNyxInsertAsset(assets, color, useUBCrowns = false) {
+    return ((useUBCrowns ? assets.crown?.nyxInsertUb?.[color] : undefined) ??
+        assets.crown?.nyxInsert?.[color]);
+}
+/**
+ * Which banners a card draws.
+ *
+ * Mirrors the renderer's conditions: crowns are legendary-only, the nickname
+ * plate needs nickname text, and the PT box needs *both* a power and a
+ * toughness — a card with only one is not a creature and gets no plate.
+ */
+export function decorationsFor(card) {
+    const legendary = card.isLegendary === true;
+    return {
+        crown: legendary,
+        crownBlackBar: legendary,
+        nickname: (card.nickname ?? "") !== "",
+        ptBox: (card.power ?? "") !== "" && (card.toughness ?? "") !== "",
+    };
+}

package/dist/layout/frameLayers.d.ts

@@ -0,0 +1,163 @@
+import type { FrameColor, FrameRef } from "../schema/frameAssets.js";
+/**
+ * The subset of Proxyshop's `LAYERS` enum the frame logic needs: canonical
+ * colour letters plus the identity labels. Mirrors Card Anvil's
+ * `utils/frameLogic.ts`, which is where the card-parsing half still lives.
+ */
+export declare const LAYERS: {
+    readonly WHITE: "W";
+    readonly BLUE: "U";
+    readonly BLACK: "B";
+    readonly RED: "R";
+    readonly GREEN: "G";
+    readonly ARTIFACT: "Artifact";
+    readonly COLORLESS: "Colorless";
+    readonly LAND: "Land";
+    readonly GOLD: "Gold";
+    readonly VEHICLE: "Vehicle";
+    readonly HYBRID: "Hybrid";
+};
+/** WUBRG in canonical order, which every multi-colour string is sorted into. */
+export declare const COLOR_ORDER: readonly ["W", "U", "B", "R", "G"];
+/** The five colour letters, for checking a string is made of them. */
+export declare const COLOR_LETTERS: ReadonlySet<string>;
+/**
+ * Two or three colours in the order cards print them (`UW` → `WU`, `UGW` →
+ * `GWU`); anything else as it came.
+ */
+export declare function printedColorOrder(colors: string): string;
+/**
+ * What the frame logic concluded about a card, before any art is chosen.
+ *
+ * This is the seam between parsing a card and picking its frame: Card Anvil
+ * derives it from a Scryfall card, and the studio builds it from a colour
+ * picker, but both feed the same selection below.
+ */
+export interface FrameDetails {
+    /** Drives the base frame: a colour, `Artifact`, `Land`, `Gold`… */
+    background: string;
+    /** Colours the pinlines and text box. */
+    pinlines: string;
+    /** Colours the name and type boxes. */
+    twins: string;
+    /** The card's colour identity; what a land's base frame uses. */
+    identity: string;
+    isColorless: boolean;
+    isHybrid: boolean;
+}
+/**
+ * Which set of frame art a card draws from. Lands use `land`, enchantments
+ * `nyx` when nyx borders are on, everything else the plain colour frames.
+ */
+export type FrameFamily = "normal" | "land" | "nyx";
+/** A mask that recolours one section of the frame. */
+export type OverlayMaskName = "pinlines" | "rules" | "titleAndType" | "title" | "rightHalf" | "rulesRight" | "adventureRules" | "adventureRulesRight" | "wings";
+export interface FrameOverlay {
+    frame: FrameRef;
+    mask: OverlayMaskName;
+    /** Applied after the primary mask. */
+    secondaryMask?: "rightHalf";
+    /** Blend RGB only, keeping the existing alpha. */
+    preserveAlpha?: boolean;
+}
+export interface FrameLayers {
+    baseFrame: FrameRef;
+    overlays?: FrameOverlay[];
+}
+/** Maps a `LAYERS` value to a single frame colour token. */
+export declare function colorToken(value: string): FrameColor;
+/** Splits a two-colour combo like `WU`, or `null` if it is not one. */
+export declare function splitTwoColor(value: string): [FrameColor, FrameColor] | null;
+/**
+ * The ref for a colour within a family.
+ *
+ * Families do not all carry every colour, and the fallbacks are deliberate:
+ * nyx has no vehicle frame, and a land that is not one of WUBRG or gold falls
+ * back to the colourless land in the base family.
+ */
+export declare function makeFamilyRef(color: FrameColor | "c2", family: FrameFamily): FrameRef;
+/** The family a type line implies. */
+export declare function frameFamily(typeLine: string, useNyxBorder?: boolean): FrameFamily;
+export interface SelectOptions {
+    readonly family?: FrameFamily;
+    /** Mask for the colourless wash over a two-colour hybrid. */
+    readonly hybridTitleMask?: "title" | "titleAndType";
+    /**
+     * Whether the layout ships a `pinlines` mask. A coloured artifact normally
+     * keeps the Artifact base and carries its colour in the overlays; a layout
+     * with no pinlines mask can never draw those, so it falls back to a
+     * colour-based base rather than losing the colour entirely.
+     */
+    readonly hasPinlineMask?: boolean;
+}
+/**
+ * The art to composite for a set of frame details.
+ *
+ * The selection half of Card Anvil's `getFrameLayers`, with the card parsing
+ * lifted out: mono and three-plus-colour cards are a single base frame, gold
+ * two-colour cards get split pinlines, and two-colour hybrids render as two
+ * halves under a colourless wash.
+ */
+export declare function selectFrameLayers(details: FrameDetails, options?: SelectOptions): FrameLayers;
+/**
+ * The art to composite for a storybook Adventure, whose text box is an open
+ * book: the card's rules on the right page, its adventure on the left.
+ *
+ * Everything outside the book is selected as for any card, as though the
+ * layout had pinlines, with one exception: the book has no pinline art, so a
+ * two-colour gold card halves its base frame between its colours, which
+ * splits the frame's own pinlines, and lays gold over the title and type bars
+ * as the regular frame has them, and over the book's page edges (`wings`).
+ * Each page is then coloured on its own: the right by the card's pinline
+ * colours, the left by `adventureColors`, the adventure's colours in the
+ * order cards print them (see `printedColorOrder`). An adventure with no
+ * colours takes the card's.
+ */
+export declare function selectStorybookFrameLayers(details: FrameDetails, adventureColors: string, options?: SelectOptions): FrameLayers;
+/**
+ * What a card is, reduced to the switches that actually change its frame.
+ *
+ * Card Anvil derives these from a Scryfall card; the studio has no card, so it
+ * offers them as controls. Everything here maps onto a real Scryfall
+ * distinction — `devoid` is the Battle for Zendikar keyword, `vehicle` and
+ * `artifact` are type-line terms, `land` and `enchantment` pick the frame
+ * family.
+ */
+export interface CardShape {
+    /** Colour identity, in any order; sorted into WUBRG here. */
+    readonly colors?: readonly FrameColor[];
+    readonly isArtifact?: boolean;
+    readonly isVehicle?: boolean;
+    readonly isLand?: boolean;
+    readonly isEnchantment?: boolean;
+    /** Devoid: coloured by identity, but framed colourless. */
+    readonly isDevoid?: boolean;
+    /** A card with no colours at all — Eldrazi, most artifacts' pinlines. */
+    readonly isColorless?: boolean;
+    /** Two colours paid with hybrid mana, which splits the frame down the middle. */
+    readonly isHybrid?: boolean;
+    /** Legendary cards get the crown. */
+    readonly isLegendary?: boolean;
+}
+/**
+ * A card's colours as one string, in the order cards print them: `GW`, not
+ * `WG`. Card Anvil orders a card's identity the same way, and a two-colour
+ * split reads its left half from the first letter, so a plain WUBRG sort
+ * would swap the halves of GW, GU and RW cards. Four colours stay WUBRG.
+ */
+export declare function orderColors(colors: readonly FrameColor[]): string;
+/**
+ * The frame details a card shape implies.
+ *
+ * Mirrors the branch order of Card Anvil's `getFrameDetailsNonland` so the
+ * studio and the app agree on the awkward cases: devoid multicolour keeps gold
+ * plates over a colourless body, a colourless card goes colourless throughout,
+ * vehicles and artifacts override the background while their colours stay in
+ * the pinlines, and a hybrid pair takes land-coloured twins.
+ *
+ * Lands are simplified on purpose: the app reads basic-land types and fetch
+ * text to infer a land's colours, which a picker states outright.
+ */
+export declare function frameDetailsFor(shape: CardShape): FrameDetails;
+/** The frame family a card shape implies, without a type line to parse. */
+export declare function familyFor(shape: CardShape, useNyxBorder?: boolean): FrameFamily;