minimojs 1.0.0-alpha.21 → 1.0.0-alpha.22

package/dist/minimo-cards.d.ts

@@ -0,0 +1,355 @@
+import { Game } from "./minimo.js";
+/**
+ * One card on a {@link CardTable}.
+ *
+ * A card is plain, serializable data. `id` must be unique on its table and
+ * `faceUp` says which side is showing. Every other field belongs to the game:
+ * a suit and rank, a value, a name, a cost, or anything else its rules need.
+ *
+ * Change where a card is with {@link CardTable.move} and which side shows with
+ * {@link CardTable.flip}. The table animates every change on its own.
+ */
+export interface Card {
+    /** Unique id on its table. Used by snapshots and by face textures. */
+    id: string;
+    /** `true` when the face is showing, `false` when the back is showing. */
+    faceUp: boolean;
+    /** Game-defined fields such as `suit`, `rank`, or `value`. */
+    [field: string]: any;
+}
+/** Suit of a card in {@link standardDeck}. */
+export type StandardSuit = "spades" | "hearts" | "diamonds" | "clubs";
+/** A card from the standard 52-card French deck built by {@link standardDeck}. */
+export interface StandardCard extends Card {
+    suit: StandardSuit;
+    /** `1` is the ace, `11` the jack, `12` the queen, and `13` the king. */
+    rank: number;
+    color: "red" | "black";
+}
+/** The four standard suits, in {@link standardDeck} order. */
+export declare const STANDARD_SUITS: readonly StandardSuit[];
+/**
+ * Builds the standard 52-card French deck, face down, ordered by suit and then
+ * by rank from ace to king.
+ *
+ * Ids are `"<suit>-<rank>"`, for example `"hearts-12"` for the queen of hearts.
+ *
+ * @example
+ * ```ts
+ * const deck = shuffle(standardDeck());
+ * ```
+ */
+export declare function standardDeck(): StandardCard[];
+/**
+ * Returns the printed rank of a standard card: `"A"`, `"2"` to `"10"`, `"J"`,
+ * `"Q"`, or `"K"`.
+ */
+export declare function rankLabel(rank: number): string;
+/**
+ * Shuffles an array in place and returns it.
+ *
+ * Without a seed the order is random. With a seed the order is always the
+ * same for that seed, which makes a deal reproducible: a numbered deal, a
+ * daily challenge, or a bug report that can be replayed.
+ *
+ * @param items - The array to shuffle. It is modified.
+ * @param seed - Optional integer seed for a reproducible order.
+ *
+ * @example
+ * ```ts
+ * shuffle(deck);        // a different deal every time
+ * shuffle(deck, 1234);  // deal number 1234, the same every time
+ * ```
+ */
+export declare function shuffle<T>(items: T[], seed?: number): T[];
+/**
+ * How a {@link CardTable} composes the fronts of {@link StandardCard}s from a
+ * game's own images. Every visual part is an image the game loaded; only the
+ * rank is text, in a web font the game declared, so a card looks the same on
+ * every device.
+ *
+ * Layout: the blank front fills the card, the rank sits in the top-left
+ * corner, the suit symbol in the top-right corner, and the middle shows the
+ * suit symbol again or, for a jack, queen, or king, its court art.
+ */
+export interface StandardFace {
+    /**
+     * Image key of an empty card front: its paper, border, and shadow. It is
+     * stretched to the card size, so draw it at the card's proportions.
+     */
+    blank: string;
+    /** Image key of each suit symbol. */
+    suits: Record<StandardSuit, string>;
+    /** Image keys of the court art. A court without one shows its suit symbol. */
+    courts?: {
+        jack?: string;
+        queen?: string;
+        king?: string;
+    };
+    /**
+     * CSS font family of the rank, such as `'"Cinzel"'`. It must be a web font
+     * the page declares and the game requires with `game.requireFont`, never a
+     * system font, whose look changes from one device to the next.
+     */
+    font: string;
+    /** Font weight of the rank. Default `"700"`. */
+    fontWeight?: string;
+    /** Rank color on hearts and diamonds. Default `"#9c1a1a"`. */
+    red?: string;
+    /** Rank color on spades and clubs. Default `"#1b1f1d"`. */
+    black?: string;
+}
+/**
+ * Which cards a drag takes from a pile when the player grabs one of them.
+ *
+ * - `"none"`: cards cannot be dragged out of this pile. Taps still arrive.
+ * - `"top"`: only the top card can be dragged.
+ * - `"tail"`: the grabbed card and every card above it move together, as in
+ *   a solitaire column.
+ * - `"any"`: any card can be dragged, alone, as from a hand.
+ *
+ * Face-down cards are never dragged.
+ */
+export type CardDragRule = "none" | "top" | "tail" | "any";
+/**
+ * Layout and interaction of one {@link CardPile}.
+ *
+ * Offsets describe how far each card sits from the card below it. With both
+ * offsets at `0`, the default, the pile is a stack where only the top card
+ * shows. A positive `offsetY` fans the pile downward like a solitaire column.
+ */
+export interface CardPileOptions {
+    /** Horizontal distance after a face-up card. Default `0`. */
+    offsetX?: number;
+    /** Vertical distance after a face-up card. Default `0`. */
+    offsetY?: number;
+    /** Horizontal distance after a face-down card. Defaults to `offsetX`. */
+    faceDownOffsetX?: number;
+    /** Vertical distance after a face-down card. Defaults to `offsetY`. */
+    faceDownOffsetY?: number;
+    /**
+     * Longest distance, in pixels, from the first card to the last. When a fan
+     * would grow past it, the offsets shrink so the pile still fits. Default: no
+     * limit.
+     */
+    maxSpread?: number;
+    /** Which cards a drag takes. Default `"top"`. See {@link CardDragRule}. */
+    drag?: CardDragRule;
+}
+/** Timing of one {@link CardTable.move} or {@link CardTable.flip}. */
+export interface CardMoveOptions {
+    /** Wait this long before the cards start moving. Default `0`. */
+    delayMs?: number;
+    /** Travel time. `0` places the cards instantly. Default: the table's `moveMs`. */
+    durationMs?: number;
+    /** Turn every moved card to this side as it travels. Default: unchanged. */
+    faceUp?: boolean;
+}
+/** Construction options of a {@link CardTable}. */
+export interface CardTableOptions {
+    /** Card width in game pixels. */
+    cardWidth: number;
+    /** Card height in game pixels. */
+    cardHeight: number;
+    /**
+     * The card fronts, always made of the game's own images:
+     *
+     * - a {@link StandardFace} composes every card of {@link standardDeck} from
+     *   a blank front, four suit symbols, optional court art, and a web font for
+     *   the rank;
+     * - a function returning an image key gives each card its own complete
+     *   front, for any other deck: numbered colors, tarot, or invented cards.
+     */
+    face: StandardFace | ((card: Card) => string);
+    /** Image key of the card back, scaled to fit the card. */
+    back: string;
+    /**
+     * Lowest sprite layer the table uses. Resting cards sit just above it,
+     * travelling cards at `layer + 500`, and dragged cards at `layer + 1000`.
+     * Default `10`.
+     */
+    layer?: number;
+    /** Default travel time of a card, in milliseconds. Default `260`. */
+    moveMs?: number;
+    /** Time of a full flip, in milliseconds. Default `220`. */
+    flipMs?: number;
+    /** Pointer travel, in pixels, before a press becomes a drag. Default `8`. */
+    dragThreshold?: number;
+}
+/**
+ * A snapshot of every pile on a {@link CardTable}, from {@link CardTable.snapshot}.
+ * It is plain JSON: keep a list of them for undo, or save one to resume later.
+ */
+export interface CardTableSnapshot {
+    /** Copies of the cards of each pile, bottom first, in pile creation order. */
+    piles: Card[][];
+}
+/**
+ * A place on a {@link CardTable} that holds an ordered list of cards: a deck,
+ * a discard pile, a solitaire column, a hand, or a slot on the table.
+ *
+ * Create piles with {@link CardTable.addPile}. `cards` is bottom first, so the
+ * last card is the top one.
+ */
+export declare class CardPile {
+    /** The table this pile belongs to. */
+    readonly table: CardTable;
+    /** Position of this pile in {@link CardTable.piles}, and in snapshots. */
+    readonly index: number;
+    /** Center of the bottom card. */
+    x: number;
+    /** Center of the bottom card. */
+    y: number;
+    /** See {@link CardPileOptions.offsetX}. */
+    offsetX: number;
+    /** See {@link CardPileOptions.offsetY}. */
+    offsetY: number;
+    /** See {@link CardPileOptions.faceDownOffsetX}. */
+    faceDownOffsetX: number;
+    /** See {@link CardPileOptions.faceDownOffsetY}. */
+    faceDownOffsetY: number;
+    /** See {@link CardPileOptions.maxSpread}. `Infinity` means no limit. */
+    maxSpread: number;
+    /** See {@link CardDragRule}. */
+    drag: CardDragRule;
+    /** The cards of this pile, bottom first. Read it; change it through the table. */
+    get cards(): readonly Card[];
+    /** Number of cards in this pile. */
+    get length(): number;
+    /** The top card, or `undefined` when the pile is empty. */
+    get top(): Card | undefined;
+    /** Position of a card in this pile, `0` for the bottom, or `-1`. */
+    indexOf(card: Card): number;
+    /**
+     * Where the card at `index` rests, as the center of the card. Use it to put
+     * a marker or a label next to a card. An index past the top gives the spot
+     * the next card would take.
+     */
+    cardPosition(index: number): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * A card table: piles of cards, their animation, and drag-and-drop between
+ * them. It is the whole card-games module.
+ *
+ * The table keeps the authoritative state, which is simply which cards are in
+ * which pile, in which order, and which side is up. Every change is applied at
+ * once, and the sprites then travel, flip, and settle to show it. Rules stay
+ * in the game: the table only asks, through `canDrag`, `canDrop`, `onDrop`,
+ * and `onTap`, and never decides what a legal move is.
+ *
+ * Call {@link update} once per frame.
+ *
+ * @example
+ * ```ts
+ * const table = new CardTable(game, {
+ *   cardWidth: 100,
+ *   cardHeight: 140,
+ *   back: "card-back",
+ *   face: {
+ *     blank: "card-front",
+ *     suits: { spades: "spade", hearts: "heart", diamonds: "diamond", clubs: "club" },
+ *     font: '"Cinzel"',
+ *   },
+ * });
+ * const deck = table.addPile(120, 200);
+ * const discard = table.addPile(260, 200);
+ * table.move(shuffle(standardDeck()), deck, { durationMs: 0 });
+ *
+ * table.onTap = (card, pile) => {
+ *   if (pile === deck && card) table.move(card, discard, { faceUp: true });
+ * };
+ * table.canDrop = (cards, from, to) => to === discard;
+ *
+ * game.onUpdate = (dt) => table.update(dt);
+ * ```
+ */
+export declare class CardTable {
+    /** The game this table draws into. */
+    readonly game: Game;
+    /** Card width in game pixels. */
+    readonly cardWidth: number;
+    /** Card height in game pixels. */
+    readonly cardHeight: number;
+    /** Lowest sprite layer the table uses. See {@link CardTableOptions.layer}. */
+    readonly layer: number;
+    /** Default travel time of a card, in milliseconds. */
+    moveMs: number;
+    /** Time of a full flip, in milliseconds. */
+    flipMs: number;
+    /** Pointer travel, in pixels, before a press becomes a drag. */
+    dragThreshold: number;
+    /** While `false`, the table ignores the pointer. Animations continue. */
+    enabled: boolean;
+    /**
+     * Asked before a drag starts, with the cards the drag would take, bottom
+     * first. Return `false` to keep them in place. Default: every face-up drag
+     * the pile's `drag` rule allows.
+     */
+    canDrag: ((cards: Card[], pile: CardPile) => boolean) | null;
+    /**
+     * Asked for each pile the dragged cards are over, to find where they may
+     * land. Return `true` if the rules allow the move. Default: any pile.
+     */
+    canDrop: ((cards: Card[], from: CardPile, to: CardPile) => boolean) | null;
+    /**
+     * Called when dragged cards are released over a pile that accepts them.
+     * Default: `table.move(cards, to)`. Replace it to also score, reveal a card,
+     * or check for a win. Cards released anywhere else return on their own.
+     */
+    onDrop: ((cards: Card[], from: CardPile, to: CardPile) => void) | null;
+    /**
+     * Called when a card, or an empty pile, is tapped without being dragged.
+     * `card` is `null` for an empty pile.
+     */
+    onTap: ((card: Card | null, pile: CardPile) => void) | null;
+    constructor(game: Game, options: CardTableOptions);
+    /** Every pile, in creation order. */
+    get piles(): readonly CardPile[];
+    /** `true` while any card is travelling, flipping, waiting to move, or being dragged. */
+    get isBusy(): boolean;
+    /** `true` while the player is dragging cards. */
+    get isDragging(): boolean;
+    /**
+     * Adds a pile whose bottom card is centered at `x`, `y`.
+     *
+     * @example
+     * ```ts
+     * const stock = table.addPile(120, 200, { drag: "none" });
+     * const column = table.addPile(300, 400, { offsetY: 40, faceDownOffsetY: 20, drag: "tail" });
+     * ```
+     */
+    addPile(x: number, y: number, options?: CardPileOptions): CardPile;
+    /** The pile that holds `card`, or `null` if the card is not on the table. */
+    pileOf(card: Card): CardPile | null;
+    /**
+     * Moves cards onto the top of a pile, in the order given, from wherever they
+     * are. A card not yet on the table appears there. The state changes now; the
+     * returned promise resolves when the cards have arrived.
+     *
+     * @example
+     * ```ts
+     * table.move(deck, stock, { durationMs: 0 });          // set up instantly
+     * await table.move(stock.top, waste, { faceUp: true }); // draw one
+     * cards.forEach((card, i) => table.move(card, hand, { delayMs: i * 80 })); // deal
+     * ```
+     */
+    move(cards: Card | Card[] | readonly Card[] | undefined, to: CardPile, options?: CardMoveOptions): Promise<void>;
+    /**
+     * Turns a card to `faceUp`, or over when `faceUp` is omitted. The promise
+     * resolves when the flip has finished.
+     */
+    flip(card: Card | undefined, faceUp?: boolean, options?: Pick<CardMoveOptions, "delayMs">): Promise<void>;
+    /** Copies the state of every pile. See {@link CardTableSnapshot}. */
+    snapshot(): CardTableSnapshot;
+    /**
+     * Puts every pile back as it was in a snapshot, moving and flipping the
+     * cards there. Cards are matched by id. Cards missing from the snapshot
+     * leave the table.
+     */
+    restore(snapshot: CardTableSnapshot, options?: Pick<CardMoveOptions, "durationMs">): Promise<void>;
+    /** Advances input and animation. Call it once per frame from `onUpdate`. */
+    update(dt: number): void;
+}

package/dist/minimo-cards.js

@@ -0,0 +1,809 @@
+import { Game, ImageSprite } from "./minimo.js";
+/** The four standard suits, in {@link standardDeck} order. */
+export const STANDARD_SUITS = ["spades", "hearts", "diamonds", "clubs"];
+/**
+ * Builds the standard 52-card French deck, face down, ordered by suit and then
+ * by rank from ace to king.
+ *
+ * Ids are `"<suit>-<rank>"`, for example `"hearts-12"` for the queen of hearts.
+ *
+ * @example
+ * ```ts
+ * const deck = shuffle(standardDeck());
+ * ```
+ */
+export function standardDeck() {
+    const deck = [];
+    for (const suit of STANDARD_SUITS) {
+        const color = suit === "hearts" || suit === "diamonds" ? "red" : "black";
+        for (let rank = 1; rank <= 13; rank++) {
+            deck.push({ id: `${suit}-${rank}`, suit, rank, color, faceUp: false });
+        }
+    }
+    return deck;
+}
+/**
+ * Returns the printed rank of a standard card: `"A"`, `"2"` to `"10"`, `"J"`,
+ * `"Q"`, or `"K"`.
+ */
+export function rankLabel(rank) {
+    if (rank === 1)
+        return "A";
+    if (rank === 11)
+        return "J";
+    if (rank === 12)
+        return "Q";
+    if (rank === 13)
+        return "K";
+    return String(rank);
+}
+/**
+ * Shuffles an array in place and returns it.
+ *
+ * Without a seed the order is random. With a seed the order is always the
+ * same for that seed, which makes a deal reproducible: a numbered deal, a
+ * daily challenge, or a bug report that can be replayed.
+ *
+ * @param items - The array to shuffle. It is modified.
+ * @param seed - Optional integer seed for a reproducible order.
+ *
+ * @example
+ * ```ts
+ * shuffle(deck);        // a different deal every time
+ * shuffle(deck, 1234);  // deal number 1234, the same every time
+ * ```
+ */
+export function shuffle(items, seed) {
+    const random = typeof seed === "number" && Number.isFinite(seed) ? seededRandom(seed) : Math.random;
+    for (let i = items.length - 1; i > 0; i--) {
+        const j = Math.floor(random() * (i + 1));
+        const swap = items[i];
+        items[i] = items[j];
+        items[j] = swap;
+    }
+    return items;
+}
+// mulberry32: small, fast, and good enough to shuffle cards reproducibly.
+function seededRandom(seed) {
+    let state = Math.floor(seed) >>> 0;
+    return () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+function isStandardCard(card) {
+    return STANDARD_SUITS.includes(card.suit) && Number.isInteger(card.rank) && card.rank >= 1 && card.rank <= 13;
+}
+function drawImageFit(ctx, image, cx, cy, maxW, maxH) {
+    const scale = Math.min(maxW / image.width, maxH / image.height);
+    const w = image.width * scale;
+    const h = image.height * scale;
+    ctx.drawImage(image, cx - w / 2, cy - h / 2, w, h);
+}
+function paintStandardFace(game, ctx, card, face, width, height) {
+    if (!isStandardCard(card)) {
+        throw new Error(`MinimoJS cards: card '${card.id}' has no standard suit and rank, so a StandardFace cannot draw it. ` +
+            "Use cards from standardDeck(), or give the table face: (card) => imageKey for any other deck.");
+    }
+    const image = (key) => game.getImage(key);
+    ctx.drawImage(image(face.blank), 0, 0, width, height);
+    const label = rankLabel(card.rank);
+    ctx.fillStyle = card.color === "red" ? face.red ?? "#9c1a1a" : face.black ?? "#1b1f1d";
+    ctx.font = `${face.fontWeight ?? "700"} ${Math.round(width * (label.length > 1 ? 0.23 : 0.295))}px ${face.font}`;
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.fillText(label, width * 0.218, height * 0.167);
+    const suit = image(face.suits[card.suit]);
+    drawImageFit(ctx, suit, width * 0.766, height * 0.192, width * 0.25, height * 0.198);
+    const courtKey = card.rank === 11 ? face.courts?.jack : card.rank === 12 ? face.courts?.queen : card.rank === 13 ? face.courts?.king : undefined;
+    if (courtKey)
+        drawImageFit(ctx, image(courtKey), width * 0.5, height * 0.616, width * 0.694, height * 0.64);
+    else
+        drawImageFit(ctx, suit, width * 0.5, height * 0.605, width * 0.613, height * 0.477);
+}
+/**
+ * A place on a {@link CardTable} that holds an ordered list of cards: a deck,
+ * a discard pile, a solitaire column, a hand, or a slot on the table.
+ *
+ * Create piles with {@link CardTable.addPile}. `cards` is bottom first, so the
+ * last card is the top one.
+ */
+export class CardPile {
+    /** @internal */
+    constructor(table, index, x, y, options = {}) {
+        /** @internal */
+        this._cards = [];
+        this.table = table;
+        this.index = index;
+        this.x = x;
+        this.y = y;
+        this.offsetX = finiteOr(options.offsetX, 0);
+        this.offsetY = finiteOr(options.offsetY, 0);
+        this.faceDownOffsetX = finiteOr(options.faceDownOffsetX, this.offsetX);
+        this.faceDownOffsetY = finiteOr(options.faceDownOffsetY, this.offsetY);
+        this.maxSpread = finiteOr(options.maxSpread, Infinity);
+        this.drag = options.drag ?? "top";
+    }
+    /** The cards of this pile, bottom first. Read it; change it through the table. */
+    get cards() {
+        return this._cards;
+    }
+    /** Number of cards in this pile. */
+    get length() {
+        return this._cards.length;
+    }
+    /** The top card, or `undefined` when the pile is empty. */
+    get top() {
+        return this._cards[this._cards.length - 1];
+    }
+    /** Position of a card in this pile, `0` for the bottom, or `-1`. */
+    indexOf(card) {
+        return this._cards.indexOf(card);
+    }
+    /**
+     * Where the card at `index` rests, as the center of the card. Use it to put
+     * a marker or a label next to a card. An index past the top gives the spot
+     * the next card would take.
+     */
+    cardPosition(index) {
+        const positions = this._layout(Math.max(index + 1, this._cards.length));
+        return positions[Math.max(0, Math.min(index, positions.length - 1))];
+    }
+    /** @internal */
+    _layout(count = this._cards.length) {
+        const steps = [];
+        let spread = 0;
+        for (let i = 0; i < count - 1; i++) {
+            const card = this._cards[i];
+            const faceUp = card ? card.faceUp : true;
+            const step = faceUp
+                ? { x: this.offsetX, y: this.offsetY }
+                : { x: this.faceDownOffsetX, y: this.faceDownOffsetY };
+            steps.push(step);
+            spread += Math.hypot(step.x, step.y);
+        }
+        const shrink = spread > this.maxSpread && spread > 0 ? this.maxSpread / spread : 1;
+        const positions = [{ x: this.x, y: this.y }];
+        for (const step of steps) {
+            const last = positions[positions.length - 1];
+            positions.push({ x: last.x + step.x * shrink, y: last.y + step.y * shrink });
+        }
+        return positions.slice(0, Math.max(0, count));
+    }
+}
+let nextTableId = 1;
+/**
+ * A card table: piles of cards, their animation, and drag-and-drop between
+ * them. It is the whole card-games module.
+ *
+ * The table keeps the authoritative state, which is simply which cards are in
+ * which pile, in which order, and which side is up. Every change is applied at
+ * once, and the sprites then travel, flip, and settle to show it. Rules stay
+ * in the game: the table only asks, through `canDrag`, `canDrop`, `onDrop`,
+ * and `onTap`, and never decides what a legal move is.
+ *
+ * Call {@link update} once per frame.
+ *
+ * @example
+ * ```ts
+ * const table = new CardTable(game, {
+ *   cardWidth: 100,
+ *   cardHeight: 140,
+ *   back: "card-back",
+ *   face: {
+ *     blank: "card-front",
+ *     suits: { spades: "spade", hearts: "heart", diamonds: "diamond", clubs: "club" },
+ *     font: '"Cinzel"',
+ *   },
+ * });
+ * const deck = table.addPile(120, 200);
+ * const discard = table.addPile(260, 200);
+ * table.move(shuffle(standardDeck()), deck, { durationMs: 0 });
+ *
+ * table.onTap = (card, pile) => {
+ *   if (pile === deck && card) table.move(card, discard, { faceUp: true });
+ * };
+ * table.canDrop = (cards, from, to) => to === discard;
+ *
+ * game.onUpdate = (dt) => table.update(dt);
+ * ```
+ */
+export class CardTable {
+    constructor(game, options) {
+        /** While `false`, the table ignores the pointer. Animations continue. */
+        this.enabled = true;
+        /**
+         * Asked before a drag starts, with the cards the drag would take, bottom
+         * first. Return `false` to keep them in place. Default: every face-up drag
+         * the pile's `drag` rule allows.
+         */
+        this.canDrag = null;
+        /**
+         * Asked for each pile the dragged cards are over, to find where they may
+         * land. Return `true` if the rules allow the move. Default: any pile.
+         */
+        this.canDrop = null;
+        /**
+         * Called when dragged cards are released over a pile that accepts them.
+         * Default: `table.move(cards, to)`. Replace it to also score, reveal a card,
+         * or check for a win. Cards released anywhere else return on their own.
+         */
+        this.onDrop = null;
+        /**
+         * Called when a card, or an empty pile, is tapped without being dragged.
+         * `card` is `null` for an empty pile.
+         */
+        this.onTap = null;
+        /** @internal */
+        this._piles = [];
+        /** @internal */
+        this._views = new Map();
+        /** @internal Standard-face textures painted so far, by texture key. */
+        this._paintedFaces = new Map();
+        /** @internal */
+        this._press = null;
+        /** @internal */
+        this._drag = null;
+        /** @internal */
+        this._flightCount = 0;
+        /** @internal Waiters for cards whose sprite is created on the next update. */
+        this._pendingWaiters = new Map();
+        if (!(game instanceof Game)) {
+            throw new Error("MinimoJS cards: new CardTable(game, options) needs the Game as its first argument.");
+        }
+        this.game = game;
+        this._id = nextTableId++;
+        this.cardWidth = Math.max(1, finiteOr(options.cardWidth, 100));
+        this.cardHeight = Math.max(1, finiteOr(options.cardHeight, 140));
+        this.layer = finiteOr(options.layer, 10);
+        this.moveMs = Math.max(0, finiteOr(options.moveMs, 260));
+        this.flipMs = Math.max(0, finiteOr(options.flipMs, 220));
+        this.dragThreshold = Math.max(0, finiteOr(options.dragThreshold, 8));
+        requireImage(game, options.back, "back");
+        this._backKey = options.back;
+        const face = options.face;
+        if (typeof face === "function") {
+            this._face = face;
+        }
+        else if (face && typeof face === "object") {
+            requireImage(game, face.blank, "face.blank");
+            for (const suit of STANDARD_SUITS)
+                requireImage(game, face.suits?.[suit], `face.suits.${suit}`);
+            for (const court of ["jack", "queen", "king"]) {
+                if (face.courts?.[court] !== undefined)
+                    requireImage(game, face.courts[court], `face.courts.${court}`);
+            }
+            if (typeof face.font !== "string" || face.font.trim().length === 0) {
+                throw new Error("MinimoJS cards: face.font must name the web font of the rank, for example '\"Cinzel\"', " +
+                    "declared by the page and required with game.requireFont.");
+            }
+            this._face = face;
+            this.whenFontReady(face);
+        }
+        else {
+            throw new Error("MinimoJS cards: new CardTable needs a face: a StandardFace built from the game's images, " +
+                "or a function that returns the image key of each card's front.");
+        }
+    }
+    /** Every pile, in creation order. */
+    get piles() {
+        return this._piles;
+    }
+    /** `true` while any card is travelling, flipping, waiting to move, or being dragged. */
+    get isBusy() {
+        if (this._drag)
+            return true;
+        for (const view of this._views.values()) {
+            if (!this.isIdle(view))
+                return true;
+        }
+        return false;
+    }
+    /** `true` while the player is dragging cards. */
+    get isDragging() {
+        return this._drag !== null;
+    }
+    /**
+     * Adds a pile whose bottom card is centered at `x`, `y`.
+     *
+     * @example
+     * ```ts
+     * const stock = table.addPile(120, 200, { drag: "none" });
+     * const column = table.addPile(300, 400, { offsetY: 40, faceDownOffsetY: 20, drag: "tail" });
+     * ```
+     */
+    addPile(x, y, options = {}) {
+        const pile = new CardPile(this, this._piles.length, x, y, options);
+        this._piles.push(pile);
+        return pile;
+    }
+    /** The pile that holds `card`, or `null` if the card is not on the table. */
+    pileOf(card) {
+        for (const pile of this._piles) {
+            if (pile._cards.includes(card))
+                return pile;
+        }
+        return null;
+    }
+    /**
+     * Moves cards onto the top of a pile, in the order given, from wherever they
+     * are. A card not yet on the table appears there. The state changes now; the
+     * returned promise resolves when the cards have arrived.
+     *
+     * @example
+     * ```ts
+     * table.move(deck, stock, { durationMs: 0 });          // set up instantly
+     * await table.move(stock.top, waste, { faceUp: true }); // draw one
+     * cards.forEach((card, i) => table.move(card, hand, { delayMs: i * 80 })); // deal
+     * ```
+     */
+    move(cards, to, options = {}) {
+        const list = toCardList(cards);
+        if (to.table !== this) {
+            throw new Error("MinimoJS cards: move() target pile belongs to another table.");
+        }
+        for (const card of list) {
+            const from = this.pileOf(card);
+            if (from)
+                from._cards.splice(from._cards.indexOf(card), 1);
+        }
+        for (const card of list) {
+            if (typeof options.faceUp === "boolean")
+                card.faceUp = options.faceUp;
+            to._cards.push(card);
+            this.schedule(card, options);
+        }
+        return this.whenIdle(list);
+    }
+    /**
+     * Turns a card to `faceUp`, or over when `faceUp` is omitted. The promise
+     * resolves when the flip has finished.
+     */
+    flip(card, faceUp, options = {}) {
+        if (!card)
+            return Promise.resolve();
+        card.faceUp = typeof faceUp === "boolean" ? faceUp : !card.faceUp;
+        this.schedule(card, options);
+        return this.whenIdle([card]);
+    }
+    /** Copies the state of every pile. See {@link CardTableSnapshot}. */
+    snapshot() {
+        return { piles: this._piles.map((pile) => pile._cards.map((card) => ({ ...card }))) };
+    }
+    /**
+     * Puts every pile back as it was in a snapshot, moving and flipping the
+     * cards there. Cards are matched by id. Cards missing from the snapshot
+     * leave the table.
+     */
+    restore(snapshot, options = {}) {
+        this.cancelDrag();
+        const byId = new Map();
+        for (const pile of this._piles)
+            for (const card of pile._cards)
+                byId.set(card.id, card);
+        for (const card of this._views.keys())
+            byId.set(card.id, card);
+        const kept = new Set();
+        this._piles.forEach((pile, i) => {
+            const saved = snapshot.piles[i] ?? [];
+            pile._cards = saved.map((data) => {
+                const card = byId.get(data.id) ?? { ...data };
+                Object.assign(card, data);
+                kept.add(card);
+                return card;
+            });
+        });
+        for (const [card, view] of this._views) {
+            if (!kept.has(card))
+                this.removeView(card, view);
+        }
+        const all = [...kept];
+        for (const card of all)
+            this.schedule(card, options);
+        return this.whenIdle(all);
+    }
+    /** Advances input and animation. Call it once per frame from `onUpdate`. */
+    update(dt) {
+        const dtMs = Math.max(0, finiteOr(dt, 0)) * 1000;
+        this.updateInput();
+        this.updateViews(dtMs);
+    }
+    // -------------------------------------------------------------------------
+    // Presentation
+    // -------------------------------------------------------------------------
+    /** @internal */
+    schedule(card, options) {
+        const view = this._views.get(card);
+        if (!view)
+            return;
+        if (typeof options.delayMs === "number" && options.delayMs > 0)
+            view.waitMs = options.delayMs;
+        if (typeof options.durationMs === "number")
+            view.nextDurationMs = Math.max(0, options.durationMs);
+    }
+    /** @internal */
+    whenIdle(cards) {
+        if (cards.length === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            let pending = cards.length;
+            const done = () => {
+                pending -= 1;
+                if (pending === 0)
+                    resolve();
+            };
+            for (const card of cards) {
+                const view = this._views.get(card);
+                if (view)
+                    view.waiters.push(done);
+                else
+                    this.pendingWaiters(card).push(done);
+            }
+        });
+    }
+    /** @internal */
+    pendingWaiters(card) {
+        let list = this._pendingWaiters.get(card);
+        if (!list) {
+            list = [];
+            this._pendingWaiters.set(card, list);
+        }
+        return list;
+    }
+    /** @internal */
+    faceKey(card) {
+        const face = this._face;
+        if (typeof face === "function") {
+            const key = face(card);
+            if (typeof key !== "string" || !this.game.hasImage(key)) {
+                throw new Error(`MinimoJS cards: front image '${key}' of card '${card.id}' is not loaded. Load it in game.onPreload.`);
+            }
+            return key;
+        }
+        const key = `cards:${this._id}:face:${card.id}`;
+        if (!this._paintedFaces.has(key)) {
+            this.paintFace(key, card, face);
+            this._paintedFaces.set(key, card);
+        }
+        return key;
+    }
+    /** @internal */
+    paintFace(key, card, face) {
+        this.game.createTexture(key, this.cardWidth, this.cardHeight, (ctx) => paintStandardFace(this.game, ctx, card, face, this.cardWidth, this.cardHeight));
+    }
+    /**
+     * @internal A face painted before its font arrived would keep the fallback
+     * font forever, so faces are repainted once the font is ready.
+     */
+    whenFontReady(face) {
+        const fonts = typeof document !== "undefined" ? document.fonts : undefined;
+        if (!fonts)
+            return;
+        const spec = `${face.fontWeight ?? "700"} 32px ${face.font}`;
+        if (fonts.check(spec))
+            return;
+        fonts.load(spec).then(() => {
+            for (const [key, card] of this._paintedFaces)
+                this.paintFace(key, card, face);
+        }, () => { });
+    }
+    /** @internal */
+    showSide(view, faceUp) {
+        const key = faceUp ? this.faceKey(view.card) : this._backKey;
+        view.sprite.setTexture(key);
+        view.shownFaceUp = faceUp;
+        this.applyScale(view);
+    }
+    /** @internal */
+    applyScale(view) {
+        const sprite = view.sprite;
+        const fit = Math.min(this.cardWidth / sprite.width, this.cardHeight / sprite.height);
+        sprite.scale = fit * (view.dragging ? 1.06 : 1);
+    }
+    /** @internal */
+    createView(card, x, y, layer) {
+        const sprite = this.game.add(new ImageSprite(this.game, this._backKey, x, y));
+        sprite.layer = layer;
+        const view = {
+            card,
+            sprite,
+            shownFaceUp: false,
+            toX: x,
+            toY: y,
+            fromX: x,
+            fromY: y,
+            elapsedMs: 0,
+            durationMs: 0,
+            moving: false,
+            flipping: false,
+            waitMs: 0,
+            nextDurationMs: null,
+            dragging: false,
+            grabX: 0,
+            grabY: 0,
+            waiters: this._pendingWaiters.get(card) ?? [],
+        };
+        this._pendingWaiters.delete(card);
+        this.showSide(view, card.faceUp);
+        this._views.set(card, view);
+        return view;
+    }
+    /** @internal */
+    removeView(card, view) {
+        this.game.destroySprite(view.sprite);
+        this._views.delete(card);
+        for (const waiter of view.waiters.splice(0))
+            waiter();
+    }
+    /** @internal */
+    isIdle(view) {
+        return !view.moving && !view.flipping && !view.dragging && view.waitMs <= 0;
+    }
+    /** @internal */
+    updateViews(dtMs) {
+        for (const pile of this._piles) {
+            const positions = pile._layout();
+            pile._cards.forEach((card, i) => {
+                const target = positions[i];
+                const restLayer = this.layer + (i + 1) * 0.01;
+                const view = this._views.get(card) ?? this.createView(card, target.x, target.y, restLayer);
+                this.updateView(view, target.x, target.y, restLayer, dtMs);
+            });
+        }
+        for (const view of this._views.values()) {
+            if (this.isIdle(view) && view.waiters.length > 0) {
+                for (const waiter of view.waiters.splice(0))
+                    waiter();
+            }
+        }
+    }
+    /** @internal */
+    updateView(view, x, y, restLayer, dtMs) {
+        if (view.dragging)
+            return;
+        if (view.waitMs > 0) {
+            view.waitMs -= dtMs;
+            if (view.waitMs > 0)
+                return;
+        }
+        const sprite = view.sprite;
+        if (x !== view.toX || y !== view.toY) {
+            const duration = view.nextDurationMs ?? this.moveMs;
+            view.nextDurationMs = null;
+            view.toX = x;
+            view.toY = y;
+            if (duration <= 0) {
+                sprite.x = x;
+                sprite.y = y;
+                view.moving = false;
+                if (view.shownFaceUp !== view.card.faceUp && !view.flipping)
+                    this.showSide(view, view.card.faceUp);
+            }
+            else {
+                view.fromX = sprite.x;
+                view.fromY = sprite.y;
+                view.elapsedMs = 0;
+                view.durationMs = duration;
+                view.moving = true;
+                this._flightCount += 1;
+                sprite.layer = this.layer + 500 + (this._flightCount % 1000) * 0.001;
+            }
+        }
+        else if (!view.moving) {
+            view.nextDurationMs = null;
+        }
+        if (view.shownFaceUp !== view.card.faceUp && !view.flipping)
+            this.startFlip(view);
+        if (view.moving) {
+            view.elapsedMs += dtMs;
+            const t = Math.min(1, view.elapsedMs / view.durationMs);
+            const eased = 1 - Math.pow(1 - t, 3);
+            sprite.x = view.fromX + (view.toX - view.fromX) * eased;
+            sprite.y = view.fromY + (view.toY - view.fromY) * eased;
+            if (t >= 1)
+                view.moving = false;
+        }
+        if (!view.moving)
+            sprite.layer = restLayer;
+    }
+    /** @internal */
+    startFlip(view) {
+        const half = this.flipMs / 2;
+        if (half <= 0) {
+            this.showSide(view, view.card.faceUp);
+            return;
+        }
+        view.flipping = true;
+        const sprite = view.sprite;
+        this.game.animateDeform(sprite, 0, 1.06, 0.5, 0.5, half, () => {
+            if (!this._views.has(view.card))
+                return;
+            this.showSide(view, view.card.faceUp);
+            this.game.animateDeform(sprite, 1, 1, 0.5, 0.5, half, () => {
+                view.flipping = false;
+            });
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Input
+    // -------------------------------------------------------------------------
+    /** @internal */
+    updateInput() {
+        const game = this.game;
+        if (!this.enabled) {
+            this._press = null;
+            this.cancelDrag();
+            return;
+        }
+        const x = game.pointerX;
+        const y = game.pointerY;
+        if (game.isPointerPressed()) {
+            this.cancelDrag();
+            const hit = this.hitTest(x, y);
+            this._press = hit ? { x, y, card: hit.card, pile: hit.pile, dragTried: false } : null;
+            return;
+        }
+        const press = this._press;
+        if (!press)
+            return;
+        if (game.isPointerDown()) {
+            if (!this._drag && !press.dragTried && Math.hypot(x - press.x, y - press.y) >= this.dragThreshold) {
+                this.startDrag(press);
+            }
+            if (this._drag)
+                this.followPointer(x, y);
+            return;
+        }
+        this._press = null;
+        if (this._drag)
+            this.finishDrag();
+        else if (Math.hypot(x - press.x, y - press.y) < this.dragThreshold)
+            this.onTap?.(press.card, press.pile);
+    }
+    /** @internal */
+    hitTest(x, y) {
+        const halfW = this.cardWidth / 2;
+        const halfH = this.cardHeight / 2;
+        for (let p = this._piles.length - 1; p >= 0; p--) {
+            const pile = this._piles[p];
+            const positions = pile._layout();
+            for (let i = pile._cards.length - 1; i >= 0; i--) {
+                const at = positions[i];
+                if (Math.abs(x - at.x) <= halfW && Math.abs(y - at.y) <= halfH) {
+                    return { card: pile._cards[i], pile };
+                }
+            }
+        }
+        for (let p = this._piles.length - 1; p >= 0; p--) {
+            const pile = this._piles[p];
+            if (pile._cards.length === 0 && Math.abs(x - pile.x) <= halfW && Math.abs(y - pile.y) <= halfH) {
+                return { card: null, pile };
+            }
+        }
+        return null;
+    }
+    /** @internal */
+    startDrag(press) {
+        const { card, pile } = press;
+        press.dragTried = true;
+        if (!card || pile.drag === "none")
+            return;
+        const index = pile._cards.indexOf(card);
+        if (index < 0)
+            return;
+        let cards;
+        if (pile.drag === "tail")
+            cards = pile._cards.slice(index);
+        else if (pile.drag === "any")
+            cards = [card];
+        else if (index === pile._cards.length - 1)
+            cards = [card];
+        else
+            return;
+        if (cards.some((c) => !c.faceUp))
+            return;
+        if (this.canDrag && this.canDrag(cards, pile) === false)
+            return;
+        this._drag = { cards, from: pile };
+        cards.forEach((c, i) => {
+            const view = this._views.get(c);
+            if (!view)
+                return;
+            view.moving = false;
+            view.waitMs = 0;
+            view.dragging = true;
+            view.grabX = press.x - view.sprite.x;
+            view.grabY = press.y - view.sprite.y;
+            view.sprite.layer = this.layer + 1000 + i * 0.01;
+            this.applyScale(view);
+        });
+    }
+    /** @internal */
+    followPointer(x, y) {
+        for (const card of this._drag?.cards ?? []) {
+            const view = this._views.get(card);
+            if (!view)
+                continue;
+            view.sprite.x = x - view.grabX;
+            view.sprite.y = y - view.grabY;
+        }
+    }
+    /** @internal */
+    finishDrag() {
+        const drag = this._drag;
+        if (!drag)
+            return;
+        const lead = this._views.get(drag.cards[0]);
+        let target = null;
+        if (lead) {
+            let best = 0;
+            for (const pile of this._piles) {
+                if (pile === drag.from)
+                    continue;
+                const area = this.dropOverlap(pile, lead.sprite.x, lead.sprite.y);
+                if (area <= best)
+                    continue;
+                if (this.canDrop && this.canDrop(drag.cards, drag.from, pile) !== true)
+                    continue;
+                best = area;
+                target = pile;
+            }
+        }
+        this.releaseDrag();
+        if (!target)
+            return;
+        if (this.onDrop)
+            this.onDrop(drag.cards, drag.from, target);
+        else
+            this.move(drag.cards, target);
+    }
+    /** @internal Overlap between the dragged lead card and the spot a pile would take it. */
+    dropOverlap(pile, x, y) {
+        const at = pile._cards.length > 0 ? pile.cardPosition(pile._cards.length - 1) : { x: pile.x, y: pile.y };
+        const overlapX = Math.max(0, this.cardWidth - Math.abs(x - at.x));
+        const overlapY = Math.max(0, this.cardHeight - Math.abs(y - at.y));
+        return overlapX * overlapY;
+    }
+    /** @internal */
+    cancelDrag() {
+        if (this._drag)
+            this.releaseDrag();
+    }
+    /** @internal */
+    releaseDrag() {
+        const drag = this._drag;
+        if (!drag)
+            return;
+        this._drag = null;
+        for (const card of drag.cards) {
+            const view = this._views.get(card);
+            if (!view)
+                continue;
+            view.dragging = false;
+            // Forces a motion from where the card was dropped back to its resting place.
+            view.toX = Number.NaN;
+            view.toY = Number.NaN;
+            view.nextDurationMs = Math.round(this.moveMs * 0.8);
+            this.applyScale(view);
+        }
+    }
+}
+function requireImage(game, key, option) {
+    if (typeof key !== "string" || !game.hasImage(key)) {
+        throw new Error(`MinimoJS cards: ${option} image '${key}' is not loaded. Card art always comes from the game's images; ` +
+            "load it with game.loadImage in game.onPreload.");
+    }
+}
+function finiteOr(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function toCardList(cards) {
+    if (!cards)
+        return [];
+    if (Array.isArray(cards))
+        return [...cards];
+    return [cards];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.21",
+  "version": "1.0.0-alpha.22",
   "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Image-first sprites with emoji as a zero-asset alternative, rAF loop, TypeScript-first, LLM-friendly.",
   "type": "module",
   "main": "dist/minimo.js",