@cardanvil/frame-kit 0.5.0 → 0.6.0

package/dist/layout/decorations.js

@@ -0,0 +1,108 @@
+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 colourless artifact takes the artifact token so its crown
+    // matches its artifact pinlines; anything else stays colourless.
+    return facts.isArtifact === true ? "a" : "c";
+}
+/** Legendary crown colour(s). */
+export function crownColors(details, facts = {}) {
+    return identityColors(details, facts);
+}
+/**
+ * Nickname banner colour(s).
+ *
+ * A land with no resolved identity uses the dedicated land nickname art rather
+ * than the colourless one.
+ */
+export function nicknameColors(details, facts = {}) {
+    if (facts.isLand === true && !details.identity) {
+        return "l";
+    }
+    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,136 @@
+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"];
+/**
+ * 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";
+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;
+/**
+ * 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;
+}
+/** WUBRG order, which every colour combination is normalised into. */
+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;

package/dist/layout/frameLayers.js

@@ -0,0 +1,291 @@
+/**
+ * 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 const LAYERS = {
+    WHITE: "W",
+    BLUE: "U",
+    BLACK: "B",
+    RED: "R",
+    GREEN: "G",
+    ARTIFACT: "Artifact",
+    COLORLESS: "Colorless",
+    LAND: "Land",
+    GOLD: "Gold",
+    VEHICLE: "Vehicle",
+    HYBRID: "Hybrid",
+};
+/** WUBRG in canonical order, which every multi-colour string is sorted into. */
+export const COLOR_ORDER = ["W", "U", "B", "R", "G"];
+const COLOR_LETTERS = new Set(COLOR_ORDER);
+/** Whether two refs point at the same family and colour. */
+function sameRef(a, b) {
+    return a.family === b.family && a.color === b.color;
+}
+/** Maps a `LAYERS` value to a single frame colour token. */
+export function colorToken(value) {
+    switch (value) {
+        case LAYERS.WHITE:
+            return "w";
+        case LAYERS.BLUE:
+            return "u";
+        case LAYERS.BLACK:
+            return "b";
+        case LAYERS.RED:
+            return "r";
+        case LAYERS.GREEN:
+            return "g";
+        case LAYERS.ARTIFACT:
+            return "a";
+        case LAYERS.COLORLESS:
+            return "c";
+        case LAYERS.LAND:
+            return "l";
+        case LAYERS.VEHICLE:
+            return "v";
+        case LAYERS.GOLD:
+            return "m";
+        case "":
+            return "c";
+        default:
+            // Three or more colours share the gold frame.
+            return "m";
+    }
+}
+/** Splits a two-colour combo like `WU`, or `null` if it is not one. */
+export function splitTwoColor(value) {
+    const [first, second] = value;
+    if (value.length === 2 &&
+        first !== undefined &&
+        second !== undefined &&
+        COLOR_LETTERS.has(first) &&
+        COLOR_LETTERS.has(second)) {
+        return [
+            first.toLowerCase(),
+            second.toLowerCase(),
+        ];
+    }
+    return 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 function makeFamilyRef(color, family) {
+    if (family === "normal") {
+        return { family: "base", color };
+    }
+    if (family === "nyx") {
+        switch (color) {
+            case "w":
+            case "u":
+            case "b":
+            case "r":
+            case "g":
+            case "m":
+            case "a":
+            case "c":
+            case "l":
+                return { family: "nyx", color };
+            case "v":
+                return { family: "nyx", color: "a" }; // there is no nyx vehicle frame
+            default:
+                return { family: "nyx", color: "c" };
+        }
+    }
+    switch (color) {
+        case "w":
+        case "u":
+        case "b":
+        case "r":
+        case "g":
+        case "m":
+            return { family: "land", color };
+        default:
+            // a / c / l / v / c2 → the colourless land, which lives in `base`.
+            return { family: "base", color: "l" };
+    }
+}
+/** The family a type line implies. */
+export function frameFamily(typeLine, useNyxBorder = true) {
+    const lower = typeLine.toLowerCase();
+    if (lower.includes("enchantment") && useNyxBorder) {
+        return "nyx";
+    }
+    return lower.includes("land") ? "land" : "normal";
+}
+/** Section overlays that recolour pinlines, text box and twins. */
+function buildSectionOverlays(details, family, baseRef) {
+    const overlays = [];
+    const pinlineSplit = splitTwoColor(details.pinlines);
+    if (pinlineSplit) {
+        // Two colours: the left colour runs full width, the right is masked to
+        // its half, for both the pinlines and the text box.
+        const first = makeFamilyRef(pinlineSplit[0], family);
+        const second = makeFamilyRef(pinlineSplit[1], family);
+        overlays.push({ frame: first, mask: "pinlines", preserveAlpha: true }, {
+            frame: second,
+            mask: "pinlines",
+            secondaryMask: "rightHalf",
+            preserveAlpha: true,
+        }, { frame: first, mask: "rules", preserveAlpha: true }, {
+            frame: second,
+            mask: "rules",
+            secondaryMask: "rightHalf",
+            preserveAlpha: true,
+        });
+    }
+    else {
+        const pinlines = makeFamilyRef(colorToken(details.pinlines), family);
+        if (!sameRef(pinlines, baseRef)) {
+            overlays.push({ frame: pinlines, mask: "pinlines", preserveAlpha: true }, { frame: pinlines, mask: "rules", preserveAlpha: true });
+        }
+    }
+    const twins = makeFamilyRef(colorToken(details.twins), family);
+    if (!sameRef(twins, baseRef)) {
+        overlays.push({ frame: twins, mask: "titleAndType", preserveAlpha: true });
+    }
+    // The border follows the background, which the base frame already supplies.
+    return overlays;
+}
+/**
+ * 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 function selectFrameLayers(details, options = {}) {
+    const { family = "normal", hybridTitleMask = "titleAndType", hasPinlineMask = true, } = options;
+    if (details.isHybrid) {
+        const split = splitTwoColor(details.pinlines);
+        if (split) {
+            return {
+                baseFrame: makeFamilyRef(split[0], family),
+                overlays: [
+                    {
+                        frame: makeFamilyRef(split[1], family),
+                        mask: "rightHalf",
+                        preserveAlpha: true,
+                    },
+                    {
+                        frame: makeFamilyRef("c2", family),
+                        mask: hybridTitleMask,
+                        preserveAlpha: true,
+                    },
+                ],
+            };
+        }
+    }
+    const usesArtifactFallback = family !== "land" &&
+        !hasPinlineMask &&
+        details.background === LAYERS.ARTIFACT &&
+        details.identity.length > 0;
+    const baseColor = colorToken(family === "land" || usesArtifactFallback
+        ? details.identity
+        : details.background);
+    const baseRef = makeFamilyRef(baseColor, family);
+    const overlays = buildSectionOverlays(details, family, baseRef);
+    return {
+        baseFrame: baseRef,
+        ...(overlays.length > 0 ? { overlays } : {}),
+    };
+}
+/** WUBRG order, which every colour combination is normalised into. */
+export function orderColors(colors) {
+    const wanted = new Set(colors.map((color) => color.toUpperCase()));
+    return COLOR_ORDER.filter((letter) => wanted.has(letter)).join("");
+}
+/**
+ * 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 function frameDetailsFor(shape) {
+    const identity = orderColors(shape.colors ?? []);
+    const details = {
+        background: identity,
+        pinlines: identity,
+        twins: identity,
+        identity,
+        isColorless: false,
+        isHybrid: false,
+    };
+    if (shape.isLand === true) {
+        // `selectFrameLayers` takes a land's base colour from `identity`; the
+        // background is always Land.
+        details.background = LAYERS.LAND;
+        if (identity.length === 0) {
+            details.pinlines = LAYERS.LAND;
+            details.twins = LAYERS.LAND;
+        }
+        else if (identity.length > 2) {
+            details.pinlines = LAYERS.GOLD;
+            details.twins = LAYERS.GOLD;
+        }
+        return details;
+    }
+    const devoid = shape.isDevoid === true && identity.length > 0;
+    const colorless = devoid ||
+        shape.isColorless === true ||
+        (identity.length === 0 && shape.isArtifact !== true);
+    if (colorless) {
+        if (devoid && identity.length > 1) {
+            details.twins = LAYERS.GOLD;
+            details.background = LAYERS.GOLD;
+        }
+        else if (!devoid) {
+            details.twins = LAYERS.COLORLESS;
+            details.background = LAYERS.COLORLESS;
+            details.pinlines = LAYERS.COLORLESS;
+        }
+        details.isColorless = true;
+        return details;
+    }
+    const hybrid = shape.isHybrid === true && identity.length === 2;
+    details.isHybrid = hybrid;
+    if (shape.isVehicle === true) {
+        details.background = LAYERS.VEHICLE;
+    }
+    else if (shape.isArtifact === true) {
+        details.background = LAYERS.ARTIFACT;
+    }
+    else if (identity.length >= 2 && !hybrid) {
+        details.background = LAYERS.GOLD;
+    }
+    if (identity.length === 0) {
+        details.pinlines = LAYERS.ARTIFACT;
+    }
+    else if (identity.length > 2) {
+        details.pinlines = LAYERS.GOLD;
+    }
+    if (identity.length === 0) {
+        details.twins = LAYERS.ARTIFACT;
+    }
+    else if (hybrid) {
+        details.twins = LAYERS.LAND;
+    }
+    else if (identity.length >= 2) {
+        details.twins = LAYERS.GOLD;
+    }
+    return details;
+}
+/** The frame family a card shape implies, without a type line to parse. */
+export function familyFor(shape, useNyxBorder = true) {
+    if (shape.isEnchantment === true && useNyxBorder) {
+        return "nyx";
+    }
+    return shape.isLand === true ? "land" : "normal";
+}

package/dist/layout/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * How a frame's art is chosen and placed.
+ *
+ * Card Anvil owns the card parsing — reading a Scryfall card into
+ * `FrameDetails` — and this owns everything downstream of it: which art a set
+ * of details selects, and where each piece is drawn. Both halves used to live
+ * in the app; this one moved here so the studio and the renderer cannot drift
+ * on it.
+ *
+ * A separate entry point from the main one: nothing on the packaging path
+ * needs it, and frames themselves never import it.
+ */
+export { CROWN_BLACK_BAR, DEFAULT_PT_IMAGE, NYX_INSERT_FALLBACK_X, type Placed, type Placement, type PlacementConfig, placeAsset, placementOrigin, } from "./assetPlacement.js";
+export { type BannerColors, type DecorationCard, type DecorationFacts, type DecorationState, crownColors, decorationsFor, identityColors, nicknameColors, ptBoxColor, resolveCrownAsset, resolveCrownNicknameAsset, resolveNicknameAsset, resolveNyxInsertAsset, resolvePtBoxAsset, } from "./decorations.js";
+export { COLOR_ORDER, type CardShape, type FrameDetails, type FrameFamily, type FrameLayers, type FrameOverlay, LAYERS, type OverlayMaskName, type SelectOptions, colorToken, familyFor, frameDetailsFor, frameFamily, makeFamilyRef, orderColors, selectFrameLayers, splitTwoColor, } from "./frameLayers.js";
+export { type ResolvedBaseFrame, resolveBaseFrame, resolveFrameAsset, } from "./resolveFrameAsset.js";

package/dist/layout/index.js

@@ -0,0 +1,16 @@
+/**
+ * How a frame's art is chosen and placed.
+ *
+ * Card Anvil owns the card parsing — reading a Scryfall card into
+ * `FrameDetails` — and this owns everything downstream of it: which art a set
+ * of details selects, and where each piece is drawn. Both halves used to live
+ * in the app; this one moved here so the studio and the renderer cannot drift
+ * on it.
+ *
+ * A separate entry point from the main one: nothing on the packaging path
+ * needs it, and frames themselves never import it.
+ */
+export { CROWN_BLACK_BAR, DEFAULT_PT_IMAGE, NYX_INSERT_FALLBACK_X, placeAsset, placementOrigin, } from "./assetPlacement.js";
+export { crownColors, decorationsFor, identityColors, nicknameColors, ptBoxColor, resolveCrownAsset, resolveCrownNicknameAsset, resolveNicknameAsset, resolveNyxInsertAsset, resolvePtBoxAsset, } from "./decorations.js";
+export { COLOR_ORDER, LAYERS, colorToken, familyFor, frameDetailsFor, frameFamily, makeFamilyRef, orderColors, selectFrameLayers, splitTwoColor, } from "./frameLayers.js";
+export { resolveBaseFrame, resolveFrameAsset, } from "./resolveFrameAsset.js";

package/dist/layout/resolveFrameAsset.d.ts

@@ -0,0 +1,31 @@
+import type { FrameAssets, FrameRef } from "../schema/frameAssets.js";
+/**
+ * Exact per-family lookup. The only alias is base `c2` → base `c`, for a frame
+ * with no distinct hybrid wash.
+ *
+ * Deliberately no cross-family fallback: a missing `land_*` or `nyx_*` variant
+ * has to resolve to `undefined` so the overlay that needed it is dropped
+ * rather than drawn in the wrong family. Falling back on the *base* frame is a
+ * separate, explicit decision — see {@link resolveBaseFrame}.
+ *
+ * Mirrors Card Anvil's `utils/resolveFrameAsset.ts`.
+ */
+export declare function resolveFrameAsset(assets: FrameAssets, ref: FrameRef): string | undefined;
+export interface ResolvedBaseFrame {
+    ref: FrameRef;
+    url: string;
+    /**
+     * True when the requested ref was missing and another colour stood in.
+     * Callers drop every overlay in that case — the overlays were composed for
+     * the frame that is not there.
+     */
+    usedFallback: boolean;
+}
+/**
+ * The base frame, with the fallback chain the renderer uses: the requested
+ * family and colour, then the same colour in `base`, then (`l` → `c`), then
+ * `m`, then `w`, then whatever the frame does ship.
+ *
+ * `undefined` only when a frame ships no base art at all.
+ */
+export declare function resolveBaseFrame(assets: FrameAssets, ref: FrameRef): ResolvedBaseFrame | undefined;

package/dist/layout/resolveFrameAsset.js

@@ -0,0 +1,58 @@
+import { FRAME_COLORS } from "../schema/frameAssets.js";
+/**
+ * Exact per-family lookup. The only alias is base `c2` → base `c`, for a frame
+ * with no distinct hybrid wash.
+ *
+ * Deliberately no cross-family fallback: a missing `land_*` or `nyx_*` variant
+ * has to resolve to `undefined` so the overlay that needed it is dropped
+ * rather than drawn in the wrong family. Falling back on the *base* frame is a
+ * separate, explicit decision — see {@link resolveBaseFrame}.
+ *
+ * Mirrors Card Anvil's `utils/resolveFrameAsset.ts`.
+ */
+export function resolveFrameAsset(assets, ref) {
+    switch (ref.family) {
+        case "base":
+            return ref.color === "c2"
+                ? (assets.base.c2 ?? assets.base.c)
+                : assets.base[ref.color];
+        case "land":
+            return assets.land?.[ref.color];
+        case "nyx":
+            return assets.nyx?.[ref.color];
+        case "tall":
+            return assets.tall?.[ref.color];
+        case "creature":
+            return assets.creature?.[ref.color];
+    }
+}
+/**
+ * The base frame, with the fallback chain the renderer uses: the requested
+ * family and colour, then the same colour in `base`, then (`l` → `c`), then
+ * `m`, then `w`, then whatever the frame does ship.
+ *
+ * `undefined` only when a frame ships no base art at all.
+ */
+export function resolveBaseFrame(assets, ref) {
+    const direct = resolveFrameAsset(assets, ref);
+    if (direct !== undefined) {
+        return { ref, url: direct, usedFallback: false };
+    }
+    const readBase = (color) => color === "c2" ? (assets.base.c2 ?? assets.base.c) : assets.base[color];
+    const chain = ref.color === "l" ? [ref.color, "c", "m", "w"] : [ref.color, "m", "w"];
+    for (const color of chain) {
+        const url = readBase(color);
+        if (url !== undefined) {
+            return { ref: { family: "base", color }, url, usedFallback: true };
+        }
+    }
+    // Last resort: the first colour the frame ships, in canonical order rather
+    // than whatever order the object happens to be written in.
+    for (const color of FRAME_COLORS) {
+        const url = assets.base[color];
+        if (url !== undefined) {
+            return { ref: { family: "base", color }, url, usedFallback: true };
+        }
+    }
+    return undefined;
+}