@cardanvil/frame-kit 0.6.0 → 0.7.0

package/dist/layout/frameLayers.js

@@ -18,7 +18,44 @@ export const LAYERS = {
 };
 /** 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);
+/** The five colour letters, for checking a string is made of them. */
+export const COLOR_LETTERS = new Set(COLOR_ORDER);
+/**
+ * Two- and three-colour combinations in the order cards print them: allied
+ * pairs then enemy pairs, shards then wedges. Mirrors Card Anvil's
+ * `frameLogic.ts` lookup.
+ */
+const PRINTED_ORDERS = [
+    "WU",
+    "UB",
+    "BR",
+    "RG",
+    "GW",
+    "WB",
+    "BG",
+    "GU",
+    "UR",
+    "RW",
+    "GWU",
+    "WUB",
+    "UBR",
+    "BRG",
+    "RGW",
+    "WBG",
+    "URW",
+    "BGU",
+    "RWB",
+    "GUR",
+];
+const sortedKey = (colors) => Array.from(colors).sort().join("");
+const PRINTED_ORDER_BY_KEY = new Map(PRINTED_ORDERS.map((combo) => [sortedKey(combo), combo]));
+/**
+ * Two or three colours in the order cards print them (`UW` → `WU`, `UGW` →
+ * `GWU`); anything else as it came.
+ */
+export function printedColorOrder(colors) {
+    return PRINTED_ORDER_BY_KEY.get(sortedKey(colors)) ?? colors;
+}
 /** Whether two refs point at the same family and colour. */
 function sameRef(a, b) {
     return a.family === b.family && a.color === b.color;
@@ -186,6 +223,26 @@ export function selectFrameLayers(details, options = {}) {
         !hasPinlineMask &&
         details.background === LAYERS.ARTIFACT &&
         details.identity.length > 0;
+    // Without a pinlines mask the split pinline overlays can never draw, so a
+    // two-colour card would fall to the gold frame; halve the base instead.
+    if (family !== "land" &&
+        !hasPinlineMask &&
+        !details.isColorless &&
+        (details.background === LAYERS.GOLD || usesArtifactFallback)) {
+        const split = splitTwoColor(details.identity);
+        if (split) {
+            return {
+                baseFrame: makeFamilyRef(split[0], family),
+                overlays: [
+                    {
+                        frame: makeFamilyRef(split[1], family),
+                        mask: "rightHalf",
+                        preserveAlpha: true,
+                    },
+                ],
+            };
+        }
+    }
     const baseColor = colorToken(family === "land" || usesArtifactFallback
         ? details.identity
         : details.background);
@@ -196,10 +253,95 @@ export function selectFrameLayers(details, options = {}) {
         ...(overlays.length > 0 ? { overlays } : {}),
     };
 }
-/** WUBRG order, which every colour combination is normalised into. */
+/**
+ * Overlays colouring one page of a storybook: a colour on its own, two with
+ * the second faded in through the page's `Right` mask, gold at three or more.
+ * A one-colour page that matches the base frame needs nothing — unless the
+ * base was halved, which runs the second colour into the pages too.
+ */
+function pageOverlays(colors, mask, rightMask, family, baseRef, halved) {
+    const split = splitTwoColor(colors);
+    if (split) {
+        return [
+            { frame: makeFamilyRef(split[0], family), mask, preserveAlpha: true },
+            {
+                frame: makeFamilyRef(split[1], family),
+                mask: rightMask,
+                preserveAlpha: true,
+            },
+        ];
+    }
+    const page = makeFamilyRef(colorToken(colors), family);
+    return sameRef(page, baseRef) && !halved
+        ? []
+        : [{ frame: page, mask, preserveAlpha: true }];
+}
+/**
+ * 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 function selectStorybookFrameLayers(details, adventureColors, options = {}) {
+    const family = options.family ?? "normal";
+    const goldSplit = details.background === LAYERS.GOLD &&
+        !details.isHybrid &&
+        !details.isColorless
+        ? splitTwoColor(details.pinlines)
+        : null;
+    const card = goldSplit
+        ? {
+            baseFrame: makeFamilyRef(goldSplit[0], family),
+            overlays: [
+                {
+                    frame: makeFamilyRef(goldSplit[1], family),
+                    mask: "rightHalf",
+                    preserveAlpha: true,
+                },
+                {
+                    frame: makeFamilyRef(colorToken(details.twins), family),
+                    mask: "titleAndType",
+                    preserveAlpha: true,
+                },
+                {
+                    frame: makeFamilyRef("m", family),
+                    mask: "wings",
+                    preserveAlpha: true,
+                },
+            ],
+        }
+        : selectFrameLayers(details, { ...options, hasPinlineMask: true });
+    // The book replaces the text box and has no pinlines, so the overlays meant
+    // for those are dropped and the pages coloured instead.
+    const kept = (card.overlays ?? []).filter((overlay) => overlay.mask !== "rules" && overlay.mask !== "pinlines");
+    const halved = kept.some((overlay) => overlay.mask === "rightHalf");
+    const overlays = [
+        ...kept,
+        ...pageOverlays(details.pinlines, "rules", "rulesRight", family, card.baseFrame, halved),
+        ...pageOverlays(adventureColors || details.pinlines, "adventureRules", "adventureRulesRight", family, card.baseFrame, halved),
+    ];
+    return {
+        baseFrame: card.baseFrame,
+        ...(overlays.length > 0 ? { overlays } : {}),
+    };
+}
+/**
+ * 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 function orderColors(colors) {
     const wanted = new Set(colors.map((color) => color.toUpperCase()));
-    return COLOR_ORDER.filter((letter) => wanted.has(letter)).join("");
+    return printedColorOrder(COLOR_ORDER.filter((letter) => wanted.has(letter)).join(""));
 }
 /**
  * The frame details a card shape implies.

package/dist/layout/index.d.ts

@@ -1,16 +1,27 @@
 /**
- * How a frame's art is chosen and placed.
+ * How a frame is drawn for one card: which art a card selects and where each
+ * piece goes, which cutouts and border recolor apply, which template settings
+ * are in effect, and how text boxes resolve and are styled.
  *
  * 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
+ * `FrameDetails` — and this owns everything downstream of it. It all used to
+ * live in the app; it 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 BorderStateInput, borderStateFor, ringMaskFor, } from "./border.js";
+export { type OverrideState, overrideMatches, resolveBoxOverrides, resolveSecondFaceBoxOverrides, } from "./boxOverrides.js";
+export { type RgbColor, getReadableTextColor, parseNormalizedCssColor, relativeLuminance, } from "./color.js";
+export { type FrameCutoutInput, frameCutoutMasks } from "./cutouts.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";
+export { COLOR_ORDER, type CardShape, type FrameDetails, type FrameFamily, type FrameLayers, type FrameOverlay, LAYERS, type OverlayMaskName, type SelectOptions, colorToken, familyFor, frameDetailsFor, frameFamily, makeFamilyRef, orderColors, printedColorOrder, selectFrameLayers, selectStorybookFrameLayers, splitTwoColor, } from "./frameLayers.js";
+export { type PaintStop, cardColorParts, gradientOffsetY, gradientStops, paintedFor, tintColor, } from "./paint.js";
+export { type ResolvedBaseFrame, hasFrameArt, resolveBaseFrame, resolveFrameAsset, } from "./resolveFrameAsset.js";
+export { type PowerToughnessRowPlacement, type PowerToughnessRowWidths, powerToughnessRow, } from "./powerToughnessRow.js";
+export { rulesSlideOffset, slideBoxes } from "./rulesSlide.js";
+export { type SettingValue, type TemplateSettingValues, layoutTemplateSettings, mergeTemplateSettings, templateSettingDefaults, } from "./settings.js";
+export { TEXT_SHADOW_COLOR, type TextOutline, type TextShadow, textOutlineFor, textShadowFor, } from "./textStyle.js";
+export { type Matrix, type Point, type Size, applyMatrix, sheetVectorInTurned, turnMatrix, turnPlacement, turnedBoundsOnSheet, turnedSheetSize, turnedVectorOnSheet, } from "./turn.js";

package/dist/layout/index.js

@@ -1,16 +1,27 @@
 /**
- * How a frame's art is chosen and placed.
+ * How a frame is drawn for one card: which art a card selects and where each
+ * piece goes, which cutouts and border recolor apply, which template settings
+ * are in effect, and how text boxes resolve and are styled.
  *
  * 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
+ * `FrameDetails` — and this owns everything downstream of it. It all used to
+ * live in the app; it 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 { borderStateFor, ringMaskFor, } from "./border.js";
+export { overrideMatches, resolveBoxOverrides, resolveSecondFaceBoxOverrides, } from "./boxOverrides.js";
+export { getReadableTextColor, parseNormalizedCssColor, relativeLuminance, } from "./color.js";
+export { frameCutoutMasks } from "./cutouts.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";
+export { COLOR_ORDER, LAYERS, colorToken, familyFor, frameDetailsFor, frameFamily, makeFamilyRef, orderColors, printedColorOrder, selectFrameLayers, selectStorybookFrameLayers, splitTwoColor, } from "./frameLayers.js";
+export { cardColorParts, gradientOffsetY, gradientStops, paintedFor, tintColor, } from "./paint.js";
+export { hasFrameArt, resolveBaseFrame, resolveFrameAsset, } from "./resolveFrameAsset.js";
+export { powerToughnessRow, } from "./powerToughnessRow.js";
+export { rulesSlideOffset, slideBoxes } from "./rulesSlide.js";
+export { layoutTemplateSettings, mergeTemplateSettings, templateSettingDefaults, } from "./settings.js";
+export { TEXT_SHADOW_COLOR, textOutlineFor, textShadowFor, } from "./textStyle.js";
+export { applyMatrix, sheetVectorInTurned, turnMatrix, turnPlacement, turnedBoundsOnSheet, turnedSheetSize, turnedVectorOnSheet, } from "./turn.js";

package/dist/layout/paint.d.ts

@@ -0,0 +1,36 @@
+import type { CardBoxes, LayoutConfig } from "../schema/frame.js";
+import type { FrameColor } from "../schema/frameAssets.js";
+import type { Gradient, TintedImage } from "../schema/paint.js";
+import { type OverrideState } from "./boxOverrides.js";
+import { type FrameDetails } from "./frameLayers.js";
+/**
+ * The colors a card paints side by side, at most `maxParts` of them; see
+ * `CardColorsSchema`. Read from the pinlines, as Proxyshop's frames do, with
+ * one difference: a three-color card's pinlines are gold, so its three come
+ * from its identity.
+ */
+export declare function cardColorParts(details: FrameDetails, maxParts?: number): FrameColor[];
+/** A gradient stop as a canvas takes it: a position, and a CSS color. */
+export interface PaintStop {
+    readonly at: number;
+    readonly color: string;
+}
+/**
+ * A gradient's stops for one card, color and opacity merged into one list a
+ * canvas can draw — a stop wherever either changes — or `undefined` when it
+ * paints nothing (its palette has no color for the card).
+ */
+export declare function gradientStops(gradient: Gradient, details: FrameDetails): PaintStop[] | undefined;
+/**
+ * How far down from its own `y` a gradient is painted for a card drawn with
+ * `boxes`, which a `rulesSlide` has moved `slideOffset`: its anchor box's top
+ * if it has one, otherwise `slideOffset` if it `slides`, else 0.
+ */
+export declare function gradientOffsetY(gradient: Gradient, boxes: CardBoxes, slideOffset: number): number;
+/**
+ * A layout as one render paints it: only the gradients and tinted images
+ * whose `when` holds for `state`. Everything else passes through untouched.
+ */
+export declare function paintedFor<Config extends Pick<LayoutConfig, "gradients" | "tintedImages">>(config: Config, state: OverrideState): Config;
+/** The color a tinted image is painted for one card, if its palette has one. */
+export declare function tintColor(image: TintedImage, details: FrameDetails): string | undefined;

package/dist/layout/paint.js

@@ -0,0 +1,148 @@
+import { overrideMatches } from "./boxOverrides.js";
+import { parseNormalizedCssColor } from "./color.js";
+import { COLOR_LETTERS, LAYERS, colorToken, printedColorOrder, } from "./frameLayers.js";
+/** Whether `value` is two or three distinct mana colors, e.g. `UW`. */
+function isColorCombo(value) {
+    return ((value.length === 2 || value.length === 3) &&
+        new Set(value).size === value.length &&
+        Array.from(value).every((letter) => COLOR_LETTERS.has(letter)));
+}
+/**
+ * The colors a card paints side by side, at most `maxParts` of them; see
+ * `CardColorsSchema`. Read from the pinlines, as Proxyshop's frames do, with
+ * one difference: a three-color card's pinlines are gold, so its three come
+ * from its identity.
+ */
+export function cardColorParts(details, maxParts = 1) {
+    const combo = isColorCombo(details.pinlines)
+        ? details.pinlines
+        : details.pinlines === LAYERS.GOLD &&
+            details.identity.length === 3 &&
+            isColorCombo(details.identity)
+            ? details.identity
+            : undefined;
+    if (combo === undefined) {
+        return [colorToken(details.pinlines)];
+    }
+    if (combo.length > maxParts) {
+        return ["m"];
+    }
+    return Array.from(printedColorOrder(combo), (letter) => colorToken(letter));
+}
+/** The palette's color for each of the card's parts, or none if any is missing. */
+function paletteColors(colors, details) {
+    const hexes = cardColorParts(details, colors.maxParts).map((part) => colors.palette[part]);
+    return hexes.every((hex) => hex !== undefined) ? hexes : [];
+}
+function rgbOf(hex) {
+    return parseNormalizedCssColor(hex) ?? { r: 0, g: 0, b: 0 };
+}
+/** Linear interpolation over stops sorted by `at`, held flat past either end. */
+function interpolate(stops, at, mix) {
+    const first = stops[0];
+    const last = stops[stops.length - 1];
+    if (!first || !last) {
+        throw new Error("interpolate: no stops");
+    }
+    if (at <= first.at) {
+        return first.value;
+    }
+    for (let i = 1; i < stops.length; i++) {
+        const before = stops[i - 1];
+        const after = stops[i];
+        if (before && after && at <= after.at) {
+            const span = after.at - before.at;
+            return mix(before.value, after.value, span > 0 ? (at - before.at) / span : 1);
+        }
+    }
+    return last.value;
+}
+const mixNumber = (a, b, t) => a + (b - a) * t;
+const mixRgb = (a, b, t) => ({
+    r: mixNumber(a.r, b.r, t),
+    g: mixNumber(a.g, b.g, t),
+    b: mixNumber(a.b, b.b, t),
+});
+/**
+ * Where each color runs along a gradient split into equal parts, as color
+ * stops: flat across its part, blending into the next over `blend` (0–1 of
+ * the length) centered on where they meet.
+ */
+function partColorStops(colors, blend) {
+    const half = Math.min(blend, 1 / colors.length) / 2;
+    return colors.flatMap((value, i) => {
+        const start = i / colors.length + (i > 0 ? half : 0);
+        const end = (i + 1) / colors.length - (i < colors.length - 1 ? half : 0);
+        return [
+            { at: start, value },
+            { at: end, value },
+        ];
+    });
+}
+const round = (value, places) => Number(value.toFixed(places));
+/**
+ * A gradient's stops for one card, color and opacity merged into one list a
+ * canvas can draw — a stop wherever either changes — or `undefined` when it
+ * paints nothing (its palette has no color for the card).
+ */
+export function gradientStops(gradient, details) {
+    const hexes = typeof gradient.color === "string"
+        ? [gradient.color]
+        : paletteColors(gradient.color, details);
+    if (hexes.length === 0) {
+        return undefined;
+    }
+    const length = gradient.direction === "horizontal" ? gradient.width : gradient.height;
+    const blend = typeof gradient.color === "string" || length <= 0
+        ? 0
+        : (gradient.color.blend ?? 0) / length;
+    const colorStops = partColorStops(hexes.map(rgbOf), blend);
+    const opacityStops = [...gradient.opacity]
+        .sort((a, b) => a.at - b.at)
+        .map(({ at, opacity }) => ({ at, value: opacity }));
+    const positions = [
+        ...new Set([...colorStops, ...opacityStops].map(({ at }) => at)),
+    ].sort((a, b) => a - b);
+    return positions.map((at) => {
+        const { r, g, b } = interpolate(colorStops, at, mixRgb);
+        const opacity = interpolate(opacityStops, at, mixNumber);
+        const channels = [Math.round(r), Math.round(g), Math.round(b)];
+        return {
+            at,
+            color: `rgba(${channels.join(", ")}, ${String(round(opacity, 4))})`,
+        };
+    });
+}
+/**
+ * How far down from its own `y` a gradient is painted for a card drawn with
+ * `boxes`, which a `rulesSlide` has moved `slideOffset`: its anchor box's top
+ * if it has one, otherwise `slideOffset` if it `slides`, else 0.
+ */
+export function gradientOffsetY(gradient, boxes, slideOffset) {
+    if (gradient.anchor) {
+        return boxes[gradient.anchor].y;
+    }
+    return gradient.slides === true ? slideOffset : 0;
+}
+/**
+ * A layout as one render paints it: only the gradients and tinted images
+ * whose `when` holds for `state`. Everything else passes through untouched.
+ */
+export function paintedFor(config, state) {
+    const holds = ({ when }) => when === undefined || overrideMatches(when, state);
+    return {
+        ...config,
+        ...(config.gradients && { gradients: config.gradients.filter(holds) }),
+        ...(config.tintedImages && {
+            tintedImages: config.tintedImages.filter(holds),
+        }),
+    };
+}
+/** The color a tinted image is painted for one card, if its palette has one. */
+export function tintColor(image, details) {
+    if (typeof image.color === "string") {
+        return image.color;
+    }
+    const hexes = paletteColors(image.color, details);
+    return hexes[Math.min(image.color.part ?? 0, hexes.length - 1)];
+}

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

@@ -11,6 +11,12 @@ import type { FrameAssets, FrameRef } from "../schema/frameAssets.js";
  * 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;

package/dist/layout/resolveFrameAsset.js

@@ -26,6 +26,14 @@ export function resolveFrameAsset(assets, ref) {
             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

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 {};