@cardanvil/frame-kit 0.6.0 → 0.7.0

package/dist/cli/trim.js

@@ -0,0 +1,251 @@
+/**
+ * Trimming: cutting full-sheet art down to the part of it that draws.
+ *
+ * Frame art is authored on the full 3264 × 4440 sheet so that it lines up by
+ * itself, but much of it covers a sliver of that: a Saga banner is under 5% of
+ * its sheet. A renderer decodes, caches and composites every pixel of an image,
+ * transparent or not, so the empty rest costs memory and time on every card.
+ * Trimmed, the image keeps only that sliver, and the frame records where it
+ * sits on the sheet.
+ *
+ * Nothing about how the art looks changes: the pixels kept are byte-for-byte
+ * the same, and the chunks that tell a decoder how to show them (colour
+ * profile, gamma) are carried over. A trimmed image also records its own
+ * position in an `oFFs` chunk, so trimming it again still reports where it
+ * sits on the sheet rather than in itself.
+ */
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { PNG } from "pngjs";
+import { PackagingError } from "./errors.js";
+/**
+ * The smallest rectangle holding every pixel that is not fully transparent,
+ * or `undefined` when the image has none.
+ */
+export function opaqueBounds({ width, height, data, }) {
+    let left = width;
+    let right = -1;
+    let top = height;
+    let bottom = -1;
+    for (let y = 0; y < height; y++) {
+        const row = y * width * 4;
+        for (let x = 0; x < width; x++) {
+            if (data[row + x * 4 + 3] !== 0) {
+                left = Math.min(left, x);
+                right = Math.max(right, x);
+                top = Math.min(top, y);
+                bottom = y;
+            }
+        }
+    }
+    return right < 0
+        ? undefined
+        : { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+}
+/** The smallest rectangle holding all of `rects`, or `undefined` for none. */
+export function unionBounds(rects) {
+    if (rects.length === 0) {
+        return undefined;
+    }
+    const left = Math.min(...rects.map((r) => r.x));
+    const top = Math.min(...rects.map((r) => r.y));
+    const right = Math.max(...rects.map((r) => r.x + r.width));
+    const bottom = Math.max(...rects.map((r) => r.y + r.height));
+    return { x: left, y: top, width: right - left, height: bottom - top };
+}
+/** `pixels` cut down to `rect`, which must lie inside them. */
+export function cropPixels(pixels, rect) {
+    const data = new Uint8Array(rect.width * rect.height * 4);
+    for (let y = 0; y < rect.height; y++) {
+        const from = ((rect.y + y) * pixels.width + rect.x) * 4;
+        data.set(pixels.data.subarray(from, from + rect.width * 4), y * rect.width * 4);
+    }
+    return { width: rect.width, height: rect.height, data };
+}
+const PNG_SIGNATURE = Buffer.from([
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
+/** Splits a PNG file into its chunks, without decoding any. */
+function readChunks(file) {
+    const chunks = [];
+    let offset = PNG_SIGNATURE.length;
+    while (offset + 12 <= file.length) {
+        const length = file.readUInt32BE(offset);
+        const end = offset + 12 + length;
+        chunks.push({
+            type: file.toString("latin1", offset + 4, offset + 8),
+            bytes: file.subarray(offset, end),
+            data: file.subarray(offset + 8, offset + 8 + length),
+        });
+        offset = end;
+    }
+    return chunks;
+}
+/**
+ * Chunks that change how a decoder shows the pixels — colour profile, gamma,
+ * chromaticities, significant bits, colour space — plus the pixel density.
+ * The encoder writes none of them, and a browser drawing the art honours
+ * every one, so each is copied from the original.
+ */
+const KEPT_CHUNKS = new Set([
+    "cHRM",
+    "cICP",
+    "gAMA",
+    "iCCP",
+    "mDCV",
+    "cLLI",
+    "sBIT",
+    "sRGB",
+    "pHYs",
+]);
+/** Where an image sits on its sheet, from an `oFFs` chunk in pixels. */
+function readOffset(chunks) {
+    const offs = chunks.find((chunk) => chunk.type === "oFFs");
+    // Unit 0 is pixels; a micrometre offset is someone else's and is ignored.
+    if (offs?.data.length === 9 && offs.data[8] === 0) {
+        return { x: offs.data.readInt32BE(0), y: offs.data.readInt32BE(4) };
+    }
+    return { x: 0, y: 0 };
+}
+const CRC_TABLE = Array.from({ length: 256 }, (_, n) => {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    }
+    return c >>> 0;
+});
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc = (CRC_TABLE[(crc ^ byte) & 0xff] ?? 0) ^ (crc >>> 8);
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const typeAndData = Buffer.concat([Buffer.from(type, "latin1"), data]);
+    const out = Buffer.alloc(12 + data.length);
+    out.writeUInt32BE(data.length, 0);
+    typeAndData.copy(out, 4);
+    out.writeUInt32BE(crc32(typeAndData), 8 + data.length);
+    return out;
+}
+function offsetChunk(x, y) {
+    const data = Buffer.alloc(9);
+    data.writeInt32BE(x, 0);
+    data.writeInt32BE(y, 4);
+    data.writeUInt8(0, 8);
+    return chunk("oFFs", data);
+}
+/**
+ * Encodes `pixels` as an RGBA PNG carrying `original`'s display chunks and an
+ * `oFFs` chunk at `at`. All of them go straight after the header, which is
+ * before any palette or image data, as the format requires.
+ */
+function encode(pixels, original, at) {
+    const png = new PNG({ width: pixels.width, height: pixels.height });
+    png.data = Buffer.from(pixels.data.buffer, pixels.data.byteOffset, pixels.data.byteLength);
+    const encoded = PNG.sync.write(png, { colorType: 6 });
+    const [header, ...rest] = readChunks(encoded);
+    if (!header) {
+        throw new Error("the PNG encoder wrote no header");
+    }
+    return Buffer.concat([
+        PNG_SIGNATURE,
+        header.bytes,
+        ...original.filter((c) => KEPT_CHUNKS.has(c.type)).map((c) => c.bytes),
+        offsetChunk(at.x, at.y),
+        ...rest.map((c) => c.bytes),
+    ]);
+}
+async function readSource(file) {
+    const bytes = await readFile(file);
+    if (!bytes.subarray(0, 8).equals(PNG_SIGNATURE)) {
+        throw new PackagingError(`${file} is not a PNG. Only PNGs have transparency to trim.`);
+    }
+    const chunks = readChunks(bytes);
+    // Decoding scales 16 bits down to 8, so writing it back would lose detail.
+    const header = chunks[0];
+    if (header?.type === "IHDR" && header.data[8] === 16) {
+        throw new PackagingError(`${file} has 16 bits a channel. Trimming keeps pixels exactly, which ` +
+            "it can only do for 8-bit images.");
+    }
+    const png = PNG.sync.read(bytes);
+    const pixels = { width: png.width, height: png.height, data: png.data };
+    return {
+        file,
+        bytes,
+        chunks,
+        pixels,
+        offset: readOffset(chunks),
+        bounds: opaqueBounds(pixels),
+    };
+}
+/**
+ * Trims each PNG in `files` to its visible pixels, or with `shared` all of
+ * them to one rectangle, and reports where each now sits on its sheet. An
+ * image already as small as it can be is not rewritten.
+ */
+export async function trimImages(files, options = {}) {
+    const sources = await Promise.all(files.map((file) => readSource(file)));
+    let shared;
+    if (options.shared) {
+        const [first] = sources;
+        const mismatched = sources.find((s) => first &&
+            (s.pixels.width !== first.pixels.width ||
+                s.pixels.height !== first.pixels.height ||
+                s.offset.x !== first.offset.x ||
+                s.offset.y !== first.offset.y));
+        if (first && mismatched) {
+            throw new PackagingError(`--shared needs images of one size at one place on the sheet, but ` +
+                `${mismatched.file} is ${String(mismatched.pixels.width)} × ` +
+                `${String(mismatched.pixels.height)} at ` +
+                `(${String(mismatched.offset.x)}, ${String(mismatched.offset.y)}) ` +
+                `and ${first.file} is ${String(first.pixels.width)} × ` +
+                `${String(first.pixels.height)} at ` +
+                `(${String(first.offset.x)}, ${String(first.offset.y)}).`);
+        }
+        shared = unionBounds(sources.flatMap((s) => (s.bounds ? [s.bounds] : [])));
+    }
+    const images = await Promise.all(sources.map(async (source) => {
+        const crop = options.shared ? shared : source.bounds;
+        const { width, height } = source.pixels;
+        const onSheet = crop && {
+            ...crop,
+            x: source.offset.x + crop.x,
+            y: source.offset.y + crop.y,
+        };
+        const unchanged = !crop ||
+            (crop.x === 0 &&
+                crop.y === 0 &&
+                crop.width === width &&
+                crop.height === height);
+        if (unchanged || options.dryRun) {
+            return {
+                file: source.file,
+                written: undefined,
+                width,
+                height,
+                kept: onSheet,
+            };
+        }
+        const target = options.outDir
+            ? path.join(options.outDir, path.basename(source.file))
+            : source.file;
+        await writeFile(target, encode(cropPixels(source.pixels, crop), source.chunks, onSheet ?? crop));
+        return {
+            file: source.file,
+            written: target,
+            width,
+            height,
+            kept: onSheet,
+        };
+    }));
+    return {
+        images,
+        shared: shared && {
+            ...shared,
+            x: (sources[0]?.offset.x ?? 0) + shared.x,
+            y: (sources[0]?.offset.y ?? 0) + shared.y,
+        },
+    };
+}

package/dist/layout/border.d.ts

@@ -0,0 +1,27 @@
+import type { BorderState } from "../schema/condition.js";
+import type { LayoutMasks } from "../schema/frameAssets.js";
+/**
+ * The mask a border color recolors the ring through: `borderFull` when
+ * "Color Entire Border" is on and the layout ships one, else the plain
+ * `border`. Undefined when the layout has no ring mask, so no border color
+ * can reach it.
+ */
+export declare function ringMaskFor(masks: LayoutMasks | undefined, useFullBorder: boolean): string | undefined;
+export interface BorderStateInput {
+    /** The border color setting, when one is picked. */
+    borderColor: string | null;
+    /** The mask set the face is drawn with. */
+    masks: LayoutMasks | undefined;
+    useNoBorder: boolean;
+    useFullBorder: boolean;
+}
+/**
+ * The border as it is about to be drawn, which text boxes' `overrides` match
+ * on (see `BorderStateSchema`).
+ *
+ * Only what the masks actually do counts: "No Border" without a `noBorder`
+ * mask cuts nothing away, and a border color without a ring mask recolors
+ * nothing — so a frame that cannot change its border always reads
+ * `"default"`.
+ */
+export declare function borderStateFor({ borderColor, masks, useNoBorder, useFullBorder, }: BorderStateInput): BorderState;

package/dist/layout/border.js

@@ -0,0 +1,31 @@
+import { getReadableTextColor, parseNormalizedCssColor } from "./color.js";
+/**
+ * The mask a border color recolors the ring through: `borderFull` when
+ * "Color Entire Border" is on and the layout ships one, else the plain
+ * `border`. Undefined when the layout has no ring mask, so no border color
+ * can reach it.
+ */
+export function ringMaskFor(masks, useFullBorder) {
+    return useFullBorder && masks?.borderFull ? masks.borderFull : masks?.border;
+}
+/**
+ * The border as it is about to be drawn, which text boxes' `overrides` match
+ * on (see `BorderStateSchema`).
+ *
+ * Only what the masks actually do counts: "No Border" without a `noBorder`
+ * mask cuts nothing away, and a border color without a ring mask recolors
+ * nothing — so a frame that cannot change its border always reads
+ * `"default"`.
+ */
+export function borderStateFor({ borderColor, masks, useNoBorder, useFullBorder, }) {
+    if (useNoBorder && masks?.noBorder) {
+        return "none";
+    }
+    const rgb = borderColor && ringMaskFor(masks, useFullBorder)
+        ? parseNormalizedCssColor(borderColor)
+        : undefined;
+    if (!rgb) {
+        return "default";
+    }
+    return getReadableTextColor(rgb) === "black" ? "light" : "dark";
+}

package/dist/layout/boxOverrides.d.ts

@@ -0,0 +1,28 @@
+import type { BorderState, RenderCondition } from "../schema/condition.js";
+import type { CardBoxes, SecondFaceBoxes } from "../schema/frame.js";
+import type { FrameColor } from "../schema/frameAssets.js";
+/** What text boxes' `overrides` are matched against, for one render. */
+export interface OverrideState {
+    /** The border as it is about to be drawn; see `BorderStateSchema`. */
+    border: BorderState;
+    /** The template settings in effect for the layout, defaults included. */
+    settings: Readonly<Record<string, unknown>>;
+    /**
+     * The card's frame color, when there is a card. A condition on it never
+     * matches without one.
+     */
+    frameColor?: FrameColor;
+}
+/**
+ * Whether every condition a `RenderCondition` names holds for one render — a
+ * text box override's, a gradient's or a tinted image's.
+ */
+export declare function overrideMatches(when: RenderCondition, state: OverrideState): boolean;
+/**
+ * A box set as the renderer draws it for one render: each text box with its
+ * matching `overrides` merged over it in order, and the list itself dropped.
+ * Bare bounds (`art`, `setSymbol`, `ptImage`) pass through untouched.
+ */
+export declare function resolveBoxOverrides(boxes: CardBoxes, state: OverrideState): CardBoxes;
+/** {@link resolveBoxOverrides} for the set a second face is drawn from. */
+export declare function resolveSecondFaceBoxOverrides(boxes: SecondFaceBoxes, state: OverrideState): SecondFaceBoxes;

package/dist/layout/boxOverrides.js

@@ -0,0 +1,95 @@
+/**
+ * The `CardBoxes` members that are text boxes, and so can carry `overrides`.
+ * `boxOverrides.test.ts` fails if the contract gains one this does not list.
+ */
+const TEXT_BOX_KEYS = [
+    "mana",
+    "title",
+    "type",
+    "rules",
+    "abilities",
+    "pt",
+    "power",
+    "toughness",
+    "collectorInfo",
+    "startingLoyalty",
+    "nicknameTitle",
+    "keyword",
+    "flipsidePt",
+    "flipsideType",
+    "flipsideManaCost",
+    "flipsideRules",
+    "insetTitle",
+    "insetMana",
+    "insetType",
+    "insetRules",
+    "defense",
+    "fuse",
+];
+/**
+ * The same for a second face's set. `boxOverrides.test.ts` holds this list to
+ * the contract too.
+ */
+const SECOND_FACE_TEXT_BOX_KEYS = [
+    "title",
+    "mana",
+    "type",
+    "rules",
+    "pt",
+    "power",
+    "toughness",
+];
+/**
+ * Whether every condition a `RenderCondition` names holds for one render — a
+ * text box override's, a gradient's or a tinted image's.
+ */
+export function overrideMatches(when, state) {
+    if (when.border !== undefined) {
+        const borders = typeof when.border === "string" ? [when.border] : when.border;
+        if (!borders.includes(state.border)) {
+            return false;
+        }
+    }
+    if (when.frameColor !== undefined) {
+        const colors = typeof when.frameColor === "string" ? [when.frameColor] : when.frameColor;
+        if (state.frameColor === undefined || !colors.includes(state.frameColor)) {
+            return false;
+        }
+    }
+    return Object.entries(when.settings ?? {}).every(([key, value]) => state.settings[key] === value);
+}
+function resolveTextBox(box, state) {
+    const { overrides = [], ...resolved } = box;
+    for (const override of overrides) {
+        if (overrideMatches(override.when, state)) {
+            Object.assign(resolved, override.style);
+        }
+    }
+    return resolved;
+}
+/**
+ * A box set as the renderer draws it for one render: each text box with its
+ * matching `overrides` merged over it in order, and the list itself dropped.
+ * Bare bounds (`art`, `setSymbol`, `ptImage`) pass through untouched.
+ */
+export function resolveBoxOverrides(boxes, state) {
+    const resolved = { ...boxes };
+    for (const key of TEXT_BOX_KEYS) {
+        const box = boxes[key];
+        if (box?.overrides) {
+            resolved[key] = resolveTextBox(box, state);
+        }
+    }
+    return resolved;
+}
+/** {@link resolveBoxOverrides} for the set a second face is drawn from. */
+export function resolveSecondFaceBoxOverrides(boxes, state) {
+    const resolved = { ...boxes };
+    for (const key of SECOND_FACE_TEXT_BOX_KEYS) {
+        const box = boxes[key];
+        if (box?.overrides) {
+            resolved[key] = resolveTextBox(box, state);
+        }
+    }
+    return resolved;
+}

package/dist/layout/color.d.ts

@@ -0,0 +1,23 @@
+export interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Parses a browser-normalized color string — what a canvas 2D context's
+ * `fillStyle` getter returns after being assigned a valid CSS color, e.g.
+ * `"#ffffff"` or `"rgba(255, 0, 0, 0.5)"`. Hex and `rgb()`/`rgba()` only: a
+ * named color has to go through a canvas first.
+ */
+export declare function parseNormalizedCssColor(normalized: string): RgbColor | undefined;
+/**
+ * WCAG relative luminance of an sRGB color (0 = black, 1 = white).
+ * https://www.w3.org/TR/WCAG20/#relativeluminancedef
+ */
+export declare function relativeLuminance({ r, g, b }: RgbColor): number;
+/**
+ * Picks whichever of black or white text has the higher WCAG contrast ratio
+ * against `background` — the standard way to choose readable text color for
+ * an arbitrary, user-chosen background (e.g. the border-color setting).
+ */
+export declare function getReadableTextColor(background: RgbColor): "black" | "white";

package/dist/layout/color.js

@@ -0,0 +1,53 @@
+/**
+ * Parses a browser-normalized color string — what a canvas 2D context's
+ * `fillStyle` getter returns after being assigned a valid CSS color, e.g.
+ * `"#ffffff"` or `"rgba(255, 0, 0, 0.5)"`. Hex and `rgb()`/`rgba()` only: a
+ * named color has to go through a canvas first.
+ */
+export function parseNormalizedCssColor(normalized) {
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(normalized.trim());
+    const digits = hex?.[1];
+    if (digits) {
+        if (digits.length === 3) {
+            const [r = "0", g = "0", b = "0"] = digits;
+            return {
+                r: parseInt(r + r, 16),
+                g: parseInt(g + g, 16),
+                b: parseInt(b + b, 16),
+            };
+        }
+        return {
+            r: parseInt(digits.slice(0, 2), 16),
+            g: parseInt(digits.slice(2, 4), 16),
+            b: parseInt(digits.slice(4, 6), 16),
+        };
+    }
+    const fn = /^rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/i.exec(normalized.trim());
+    const [, rStr, gStr, bStr] = fn ?? [];
+    if (rStr && gStr && bStr) {
+        return { r: Number(rStr), g: Number(gStr), b: Number(bStr) };
+    }
+    return undefined;
+}
+/**
+ * WCAG relative luminance of an sRGB color (0 = black, 1 = white).
+ * https://www.w3.org/TR/WCAG20/#relativeluminancedef
+ */
+export function relativeLuminance({ r, g, b }) {
+    const linear = (channel) => {
+        const c = channel / 255;
+        return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+    };
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+/**
+ * Picks whichever of black or white text has the higher WCAG contrast ratio
+ * against `background` — the standard way to choose readable text color for
+ * an arbitrary, user-chosen background (e.g. the border-color setting).
+ */
+export function getReadableTextColor(background) {
+    const l = relativeLuminance(background);
+    const contrastWithWhite = 1.05 / (l + 0.05);
+    const contrastWithBlack = (l + 0.05) / 0.05;
+    return contrastWithWhite >= contrastWithBlack ? "white" : "black";
+}

package/dist/layout/cutouts.d.ts

@@ -0,0 +1,28 @@
+import type { BaseColor, FrameAssets, LayoutMasks } from "../schema/frameAssets.js";
+export interface FrameCutoutInput {
+    /** The mask set the face is drawn with. */
+    masks: LayoutMasks | undefined;
+    frameAssets: FrameAssets;
+    useNoBorder: boolean;
+    isLegendary: boolean;
+    hasNickname: boolean;
+    /** The base frame's color, after any fallback. */
+    frameColor: BaseColor;
+    /** The planeswalker 4+-ability ("tall") base frame is in use. */
+    isTallFrame: boolean;
+}
+/**
+ * The masks cut out of a face's combined frame — base art plus section
+ * overlays — in the order the renderer applies them as `destination-in`, each
+ * seeing the result of the one before:
+ *
+ * - `noBorder`, when "No Border" is on;
+ * - `legendary`, on a legendary card;
+ * - `extended`, whenever the layout ships it (the extended-art silhouette);
+ * - the planeswalker colorless-nickname banner cutout, on a nicknamed
+ *   colorless card.
+ *
+ * Crowns, nickname plates and PT boxes are drawn afterwards, over the result,
+ * so none of these cut them.
+ */
+export declare function frameCutoutMasks(input: FrameCutoutInput): string[];

package/dist/layout/cutouts.js

@@ -0,0 +1,29 @@
+/**
+ * The masks cut out of a face's combined frame — base art plus section
+ * overlays — in the order the renderer applies them as `destination-in`, each
+ * seeing the result of the one before:
+ *
+ * - `noBorder`, when "No Border" is on;
+ * - `legendary`, on a legendary card;
+ * - `extended`, whenever the layout ships it (the extended-art silhouette);
+ * - the planeswalker colorless-nickname banner cutout, on a nicknamed
+ *   colorless card.
+ *
+ * Crowns, nickname plates and PT boxes are drawn afterwards, over the result,
+ * so none of these cut them.
+ */
+export function frameCutoutMasks(input) {
+    const { masks, frameAssets, useNoBorder, isLegendary, hasNickname, frameColor, isTallFrame, } = input;
+    const nicknameMasks = frameAssets.planeswalker?.colorlessNicknameMasks;
+    const colorlessNickname = frameColor === "c" && hasNickname
+        ? isTallFrame
+            ? nicknameMasks?.tall
+            : nicknameMasks?.regular
+        : undefined;
+    return [
+        useNoBorder ? masks?.noBorder : undefined,
+        isLegendary ? masks?.legendary : undefined,
+        masks?.extended,
+        colorlessNickname,
+    ].filter((url) => Boolean(url));
+}

package/dist/layout/decorations.d.ts

@@ -23,12 +23,7 @@ export type BannerColors = FrameColor | [FrameColor, FrameColor];
 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).
- *
- * A land with no resolved identity uses the dedicated land nickname art rather
- * than the colourless one.
- */
+/** Nickname banner colour(s). */
 export declare function nicknameColors(details: FrameDetails, facts?: DecorationFacts): BannerColors;
 /**
  * PT box colour.

package/dist/layout/decorations.js

@@ -17,24 +17,20 @@ export function identityColors(details, facts = {}) {
     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.
+    // 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).
- *
- * A land with no resolved identity uses the dedicated land nickname art rather
- * than the colourless one.
- */
+/** Nickname banner colour(s). */
 export function nicknameColors(details, facts = {}) {
-    if (facts.isLand === true && !details.identity) {
-        return "l";
-    }
     return identityColors(details, facts);
 }
 /**

package/dist/layout/frameLayers.d.ts

@@ -19,6 +19,13 @@ export declare const LAYERS: {
 };
 /** 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.
  *
@@ -44,7 +51,7 @@ export interface FrameDetails {
  */
 export type FrameFamily = "normal" | "land" | "nyx";
 /** A mask that recolours one section of the frame. */
-export type OverlayMaskName = "pinlines" | "rules" | "titleAndType" | "title" | "rightHalf";
+export type OverlayMaskName = "pinlines" | "rules" | "titleAndType" | "title" | "rightHalf" | "rulesRight" | "adventureRules" | "adventureRulesRight" | "wings";
 export interface FrameOverlay {
     frame: FrameRef;
     mask: OverlayMaskName;
@@ -92,6 +99,21 @@ export interface SelectOptions {
  * 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.
  *
@@ -117,7 +139,12 @@ export interface CardShape {
     /** Legendary cards get the crown. */
     readonly isLegendary?: boolean;
 }
-/** WUBRG order, which every colour combination is normalised into. */
+/**
+ * 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.