@cardanvil/frame-kit 0.5.0 → 0.7.0

package/dist/layout/powerToughnessRow.d.ts

@@ -0,0 +1,26 @@
+import type { PowerToughnessRow } from "../schema/frame.js";
+/** How wide each part of a `powerToughnessRow` is drawn, in sheet px. */
+export interface PowerToughnessRowWidths {
+    power: number;
+    toughness: number;
+    /** The widest image in the power's `ptSlot`; 0, or left out, for none. */
+    powerSymbol?: number;
+    /** The widest image in the toughness's `ptSlot`; 0, or left out, for none. */
+    toughnessSymbol?: number;
+}
+/** Where a `powerToughnessRow` puts each part, in sheet x. */
+export interface PowerToughnessRowPlacement {
+    /** The power number's left edge. */
+    power: number;
+    /** The toughness number's left edge. */
+    toughness: number;
+    /** Where the power's symbols end: their right edge. */
+    powerSymbol: number;
+    /** Where the toughness's symbols end: their right edge. */
+    toughnessSymbol: number;
+}
+/**
+ * Lays out a `powerToughnessRow` from its right edge: the toughness, its
+ * symbol, the power, then the power's symbol, each left of the one before.
+ */
+export declare function powerToughnessRow(row: PowerToughnessRow, widths: PowerToughnessRowWidths): PowerToughnessRowPlacement;

package/dist/layout/powerToughnessRow.js

@@ -0,0 +1,13 @@
+/**
+ * Lays out a `powerToughnessRow` from its right edge: the toughness, its
+ * symbol, the power, then the power's symbol, each left of the one before.
+ */
+export function powerToughnessRow(row, widths) {
+    const toughness = row.right - widths.toughness;
+    const toughnessSymbol = toughness - row.gap;
+    const power = toughnessSymbol -
+        (widths.toughnessSymbol ?? 0) -
+        row.spacing -
+        widths.power;
+    return { power, toughness, powerSymbol: power - row.gap, toughnessSymbol };
+}

package/dist/layout/resolveFrameAsset.d.ts

@@ -0,0 +1,37 @@
+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;
+/**
+ * Whether a layout has frame art at all. One whose `base` is empty has none:
+ * its art runs to the edges, and whatever it puts over the art — gradients,
+ * tinted images, text — is all there is.
+ */
+export declare function hasFrameArt(assets: FrameAssets): boolean;
+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,66 @@
+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];
+    }
+}
+/**
+ * Whether a layout has frame art at all. One whose `base` is empty has none:
+ * its art runs to the edges, and whatever it puts over the art — gradients,
+ * tinted images, text — is all there is.
+ */
+export function hasFrameArt(assets) {
+    return Object.values(assets.base).length > 0;
+}
+/**
+ * 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;
+}

package/dist/layout/rulesSlide.d.ts

@@ -0,0 +1,13 @@
+import type { CardBoxes, RulesSlide } from "../schema/frame.js";
+/**
+ * How far a `rulesSlide` moves the boxes for rules text `textHeight` tall in
+ * a `rules` box `boxHeight` tall: the room left over less `padding`, rounded
+ * down to whole steps, at most `maxSteps` of them.
+ */
+export declare function rulesSlideOffset(slide: RulesSlide, boxHeight: number, textHeight: number): number;
+/**
+ * The boxes once a `rulesSlide` has moved them down by `offset`: the listed
+ * boxes moved whole, and the `rules` box's top moved with them while its
+ * bottom stays put.
+ */
+export declare function slideBoxes(boxes: CardBoxes, slide: RulesSlide, offset: number): CardBoxes;

package/dist/layout/rulesSlide.js

@@ -0,0 +1,33 @@
+/**
+ * How far a `rulesSlide` moves the boxes for rules text `textHeight` tall in
+ * a `rules` box `boxHeight` tall: the room left over less `padding`, rounded
+ * down to whole steps, at most `maxSteps` of them.
+ */
+export function rulesSlideOffset(slide, boxHeight, textHeight) {
+    const room = boxHeight - textHeight - slide.padding;
+    const steps = Math.min(slide.maxSteps, Math.floor(room / slide.step));
+    return steps > 0 ? steps * slide.step : 0;
+}
+/**
+ * The boxes once a `rulesSlide` has moved them down by `offset`: the listed
+ * boxes moved whole, and the `rules` box's top moved with them while its
+ * bottom stays put.
+ */
+export function slideBoxes(boxes, slide, offset) {
+    if (offset === 0) {
+        return boxes;
+    }
+    const slid = { ...boxes };
+    for (const key of slide.boxes) {
+        const box = boxes[key];
+        Object.assign(slid, { [key]: { ...box, y: box.y + offset } });
+    }
+    if (boxes.rules) {
+        slid.rules = {
+            ...boxes.rules,
+            y: boxes.rules.y + offset,
+            height: boxes.rules.height - offset,
+        };
+    }
+    return slid;
+}

package/dist/layout/settings.d.ts

@@ -0,0 +1,26 @@
+import type { Frame } from "../schema/frame.js";
+/** One template setting's value. */
+export type SettingValue = boolean | string | number;
+/**
+ * A frame's template settings as an app stores them: frame-level values as
+ * top-level keys, and each layout's own settings as a sub-object under the
+ * layout's name.
+ */
+export type TemplateSettingValues = Record<string, SettingValue | Record<string, SettingValue>>;
+/**
+ * A frame's declared defaults, in that shape. Only `config.layouts`
+ * contributes layout settings — an alternate layout shares its base layout's.
+ */
+export declare function templateSettingDefaults(frame: Frame): TemplateSettingValues;
+/**
+ * Merges a sparse override onto a base, one level deep so per-layout
+ * sub-objects merge by key rather than being replaced wholesale.
+ */
+export declare function mergeTemplateSettings(base: TemplateSettingValues | undefined, override: TemplateSettingValues | undefined): TemplateSettingValues | undefined;
+/**
+ * The settings in effect for one layout — what the renderer reads, and what a
+ * text box's `when.settings` matches: the frame-level values with the
+ * layout's own sub-object laid over them. Other layouts' sub-objects are left
+ * out.
+ */
+export declare function layoutTemplateSettings(settings: TemplateSettingValues | undefined, layout: string): Record<string, SettingValue>;

package/dist/layout/settings.js

@@ -0,0 +1,62 @@
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * A frame's declared defaults, in that shape. Only `config.layouts`
+ * contributes layout settings — an alternate layout shares its base layout's.
+ */
+export function templateSettingDefaults(frame) {
+    const defaults = {};
+    for (const [key, setting] of Object.entries(frame.templateSettings ?? {})) {
+        defaults[key] = setting.defaultValue;
+    }
+    for (const [layout, config] of Object.entries(frame.config.layouts)) {
+        const settings = config.templateSettings;
+        if (!settings) {
+            continue;
+        }
+        const layoutDefaults = {};
+        for (const [key, setting] of Object.entries(settings)) {
+            layoutDefaults[key] = setting.defaultValue;
+        }
+        defaults[layout] = layoutDefaults;
+    }
+    return defaults;
+}
+/**
+ * Merges a sparse override onto a base, one level deep so per-layout
+ * sub-objects merge by key rather than being replaced wholesale.
+ */
+export function mergeTemplateSettings(base, override) {
+    if (!override) {
+        return base;
+    }
+    if (!base) {
+        return override;
+    }
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        const baseValue = result[key];
+        result[key] =
+            isPlainObject(value) && isPlainObject(baseValue)
+                ? { ...baseValue, ...value }
+                : value;
+    }
+    return result;
+}
+/**
+ * The settings in effect for one layout — what the renderer reads, and what a
+ * text box's `when.settings` matches: the frame-level values with the
+ * layout's own sub-object laid over them. Other layouts' sub-objects are left
+ * out.
+ */
+export function layoutTemplateSettings(settings, layout) {
+    const inEffect = {};
+    for (const [key, value] of Object.entries(settings ?? {})) {
+        if (!isPlainObject(value)) {
+            inEffect[key] = value;
+        }
+    }
+    const own = settings?.[layout];
+    return isPlainObject(own) ? { ...inEffect, ...own } : inEffect;
+}

package/dist/layout/textStyle.d.ts

@@ -0,0 +1,29 @@
+import type { TextBox } from "../schema/frame.js";
+/** The color plain-text drop shadows are drawn in. */
+export declare const TEXT_SHADOW_COLOR = "#17191b";
+export interface TextOutline {
+    color: string;
+    width: number;
+}
+export interface TextShadow {
+    color: string;
+    /** In canvas pixels. */
+    offsetX: number;
+    offsetY: number;
+    /** In canvas pixels; 0 is a hard edge. */
+    blur: number;
+}
+type StyledBox = Pick<TextBox, "fontSize" | "outlineColor" | "outlineWidth" | "shadow" | "shadowOffsetX" | "shadowOffsetY" | "shadowBlur">;
+/** A box's outline, when it sets both an `outlineColor` and an `outlineWidth`. */
+export declare function textOutlineFor(box: StyledBox): TextOutline | undefined;
+/**
+ * The drop shadow a plain-text box — title, type, P/T, nickname title,
+ * collector info — is drawn with: only when it asks for one with `shadow`,
+ * and never alongside an outline, which always wins. The offsets default to
+ * fractions of the box's `fontSize`, unless the box sets its own.
+ *
+ * Symbols read `shadow` differently (on unless turned off), so this is for
+ * plain text only.
+ */
+export declare function textShadowFor(box: StyledBox): TextShadow | undefined;
+export {};

package/dist/layout/textStyle.js

@@ -0,0 +1,28 @@
+/** The color plain-text drop shadows are drawn in. */
+export const TEXT_SHADOW_COLOR = "#17191b";
+/** A box's outline, when it sets both an `outlineColor` and an `outlineWidth`. */
+export function textOutlineFor(box) {
+    return box.outlineColor && box.outlineWidth
+        ? { color: box.outlineColor, width: box.outlineWidth }
+        : undefined;
+}
+/**
+ * The drop shadow a plain-text box — title, type, P/T, nickname title,
+ * collector info — is drawn with: only when it asks for one with `shadow`,
+ * and never alongside an outline, which always wins. The offsets default to
+ * fractions of the box's `fontSize`, unless the box sets its own.
+ *
+ * Symbols read `shadow` differently (on unless turned off), so this is for
+ * plain text only.
+ */
+export function textShadowFor(box) {
+    if (!box.shadow || textOutlineFor(box)) {
+        return undefined;
+    }
+    return {
+        color: TEXT_SHADOW_COLOR,
+        offsetX: box.shadowOffsetX ?? -(box.fontSize * 0.029),
+        offsetY: box.shadowOffsetY ?? box.fontSize * 0.075,
+        blur: box.shadowBlur ?? 0,
+    };
+}

package/dist/layout/turn.d.ts

@@ -0,0 +1,54 @@
+import type { Bounds, Rotation } from "../schema/frame.js";
+/**
+ * The geometry of a turned box set — one whose `rotation` says the card is
+ * turned to read it (see `CardBoxesSchema`).
+ *
+ * Two spaces are in play. The **sheet** is the canvas as printed, and never
+ * turns. A set's **turned space** is that sheet as it lies once the card has
+ * been turned `rotation` degrees clockwise, which is where the set's boxes are
+ * measured. Everything here maps the second onto the first.
+ */
+export interface Size {
+    width: number;
+    height: number;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+/**
+ * A 2D affine transform in the order a canvas takes one:
+ * `x' = a·x + c·y + e`, `y' = b·x + d·y + f`.
+ */
+export type Matrix = readonly [
+    a: number,
+    b: number,
+    c: number,
+    d: number,
+    e: number,
+    f: number
+];
+/** The sheet as a turned set sees it: a quarter turn swaps its sides. */
+export declare function turnedSheetSize(sheet: Size, rotation: Rotation | undefined): Size;
+/**
+ * Where a turned set's origin lands on the sheet and how far it is rotated
+ * there, in degrees clockwise — the `x`, `y` and `rotation` of a node that
+ * draws the set. Turning the card clockwise to read a set means the set
+ * itself sits counter-clockwise on the sheet, hence the opposite sign.
+ */
+export declare function turnPlacement(sheet: Size, rotation: Rotation | undefined): Point & {
+    rotation: number;
+};
+/** {@link turnPlacement} as a matrix taking turned space to the sheet. */
+export declare function turnMatrix(sheet: Size, rotation: Rotation | undefined): Matrix;
+/** A point in a matrix's source space, in its target space. */
+export declare function applyMatrix(matrix: Matrix, point: Point): Point;
+/** The rectangle a turned set's box covers on the sheet. */
+export declare function turnedBoundsOnSheet(bounds: Bounds, sheet: Size, rotation: Rotation | undefined): Bounds;
+/**
+ * A direction in a turned set's space, as a direction on the sheet. Only the
+ * turn applies; a direction has no position to translate.
+ */
+export declare function turnedVectorOnSheet(vector: Point, rotation: Rotation | undefined): Point;
+/** The reverse of {@link turnedVectorOnSheet}. */
+export declare function sheetVectorInTurned(vector: Point, rotation: Rotation | undefined): Point;

package/dist/layout/turn.js

@@ -0,0 +1,107 @@
+/** The sheet as a turned set sees it: a quarter turn swaps its sides. */
+export function turnedSheetSize(sheet, rotation) {
+    return rotation === 90 || rotation === 270
+        ? { width: sheet.height, height: sheet.width }
+        : { width: sheet.width, height: sheet.height };
+}
+/**
+ * Where a turned set's origin lands on the sheet and how far it is rotated
+ * there, in degrees clockwise — the `x`, `y` and `rotation` of a node that
+ * draws the set. Turning the card clockwise to read a set means the set
+ * itself sits counter-clockwise on the sheet, hence the opposite sign.
+ */
+export function turnPlacement(sheet, rotation) {
+    switch (rotation) {
+        case 90:
+            return { x: 0, y: sheet.height, rotation: -90 };
+        case 180:
+            return { x: sheet.width, y: sheet.height, rotation: 180 };
+        case 270:
+            return { x: sheet.width, y: 0, rotation: 90 };
+        default:
+            return { x: 0, y: 0, rotation: 0 };
+    }
+}
+/** {@link turnPlacement} as a matrix taking turned space to the sheet. */
+export function turnMatrix(sheet, rotation) {
+    switch (rotation) {
+        case 90:
+            return [0, -1, 1, 0, 0, sheet.height];
+        case 180:
+            return [-1, 0, 0, -1, sheet.width, sheet.height];
+        case 270:
+            return [0, 1, -1, 0, sheet.width, 0];
+        default:
+            return [1, 0, 0, 1, 0, 0];
+    }
+}
+/** A point in a matrix's source space, in its target space. */
+export function applyMatrix(matrix, point) {
+    const [a, b, c, d, e, f] = matrix;
+    return {
+        x: a * point.x + c * point.y + e,
+        y: b * point.x + d * point.y + f,
+    };
+}
+/** The rectangle a turned set's box covers on the sheet. */
+export function turnedBoundsOnSheet(bounds, sheet, rotation) {
+    switch (rotation) {
+        case 90:
+            return {
+                x: bounds.y,
+                y: sheet.height - bounds.x - bounds.width,
+                width: bounds.height,
+                height: bounds.width,
+            };
+        case 180:
+            return {
+                x: sheet.width - bounds.x - bounds.width,
+                y: sheet.height - bounds.y - bounds.height,
+                width: bounds.width,
+                height: bounds.height,
+            };
+        case 270:
+            return {
+                x: sheet.width - bounds.y - bounds.height,
+                y: bounds.x,
+                width: bounds.height,
+                height: bounds.width,
+            };
+        default:
+            return {
+                x: bounds.x,
+                y: bounds.y,
+                width: bounds.width,
+                height: bounds.height,
+            };
+    }
+}
+/**
+ * A direction in a turned set's space, as a direction on the sheet. Only the
+ * turn applies; a direction has no position to translate.
+ */
+export function turnedVectorOnSheet(vector, rotation) {
+    switch (rotation) {
+        case 90:
+            return { x: vector.y, y: -vector.x };
+        case 180:
+            return { x: -vector.x, y: -vector.y };
+        case 270:
+            return { x: -vector.y, y: vector.x };
+        default:
+            return { x: vector.x, y: vector.y };
+    }
+}
+/** The reverse of {@link turnedVectorOnSheet}. */
+export function sheetVectorInTurned(vector, rotation) {
+    switch (rotation) {
+        case 90:
+            return { x: -vector.y, y: vector.x };
+        case 180:
+            return { x: -vector.x, y: -vector.y };
+        case 270:
+            return { x: vector.y, y: -vector.x };
+        default:
+            return { x: vector.x, y: vector.y };
+    }
+}