jaml-ui 0.1.0 → 0.2.0

package/dist/decode/motelyItemDecoder.d.ts

@@ -6,18 +6,62 @@
  *   0x1000 = PlayingCard, 0x2000 = Spectral, 0x3000 = Tarot,
  *   0x4000 = Planet, 0x5000 = Joker, 0xF000 = Invalid
  */
+import { type CardCategory } from "../utils/itemUtils.js";
+export type MotelyItemInput = number | MotelyRuntimeItem | null | undefined;
+export interface MotelyRuntimeItem {
+    type?: number;
+    value?: number;
+    edition?: number;
+    seal?: number;
+    enhancement?: number;
+    suit?: number;
+    rank?: number;
+}
+export type MotelyRenderableCategory = CardCategory | "unknown";
+export interface DecodedMotelyItem {
+    itemType: number;
+    enumKey: string;
+    displayName: string;
+    category: MotelyRenderableCategory;
+    edition: "Foil" | "Holographic" | "Polychrome" | "Negative" | null;
+    seal: "Gold" | "Red" | "Blue" | "Purple" | null;
+    enhancement: string | null;
+    rank: string | null;
+    suit: "Clubs" | "Diamonds" | "Hearts" | "Spades" | null;
+}
+export interface MotelyJamlCard {
+    type: "joker" | "consumable" | "playing";
+    card: {
+        name: string;
+        edition?: "Foil" | "Holographic" | "Polychrome" | "Negative";
+        seal?: string;
+        enhancements?: string[];
+        rank?: string;
+        suit?: string;
+        scale?: number;
+    };
+}
+export declare function resolveMotelyItemType(input: MotelyItemInput): number | null;
+export declare function motelyItemRenderCategory(input: MotelyItemInput): MotelyRenderableCategory;
+export declare function motelyItemEditionName(input: MotelyItemInput): "Foil" | "Holographic" | "Polychrome" | "Negative" | null;
+export declare function motelyItemSealName(input: MotelyItemInput): "Gold" | "Red" | "Blue" | "Purple" | null;
+export declare function motelyItemEnhancementName(input: MotelyItemInput): string | null;
+export declare function motelyPlayingCardSuitName(input: MotelyItemInput): "Clubs" | "Diamonds" | "Hearts" | "Spades" | null;
+export declare function motelyPlayingCardRankName(input: MotelyItemInput): string | null;
 /** Get the enum key name for a MotelyItemType value. */
-export declare function motelyItemTypeName(itemType: number): string;
+export declare function motelyItemTypeName(input: MotelyItemInput): string;
 /** Get the category string for a MotelyItemType value. */
-export declare function motelyItemCategory(itemType: number): string;
+export declare function motelyItemCategory(input: MotelyItemInput): string;
 /** Convert PascalCase enum key to display name. */
-export declare function motelyItemDisplayName(itemType: number): string;
+export declare function motelyItemDisplayName(input: MotelyItemInput): string;
+export declare function decodeMotelyItem(input: MotelyItemInput): DecodedMotelyItem | null;
+export declare function decodeMotelyItemToJamlCard(input: MotelyItemInput, scale?: number): MotelyJamlCard | null;
 /**
  * Decode a MotelyItemType integer to a display name for sprite lookup.
  * Cached per value.
  */
-export declare function decodeMotelyItemName(itemType: number): string | null;
+export declare function decodeMotelyItemName(input: MotelyItemInput): string | null;
 /** Warm the cache for a batch of item type values. */
-export declare function warmMotelyItemCache(itemTypes: readonly number[]): void;
+export declare function warmMotelyItemCache(itemTypes: readonly MotelyItemInput[]): void;
 /** Number of unique items decoded so far. */
 export declare function motelyItemCacheSize(): number;

package/dist/decode/motelyItemDecoder.js

@@ -7,8 +7,13 @@
  *   0x4000 = Planet, 0x5000 = Joker, 0xF000 = Invalid
  */
 import { Motely } from "motely-wasm";
+import { getItemCategory, getItemDisplayName } from "../utils/itemUtils.js";
 // ─── Category from MotelyItemType integer ────────────────────────────────────
 const CATEGORY_MASK = 0xf000;
+const VALUE_TYPE_MASK = 0xffff;
+const VALUE_SEAL_MASK = 0x70000;
+const VALUE_ENHANCEMENT_MASK = 0x780000;
+const VALUE_EDITION_MASK = 0x3800000;
 const CATEGORY_TO_TYPE = {
     0x1000: "Playing Card",
     0x2000: "Spectral",
@@ -28,27 +33,238 @@ function ensureItemTypeMap() {
         }
     }
 }
+function asRuntimeItem(input) {
+    return input !== null && typeof input === "object" ? input : null;
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function runtimeEnumName(enumObject, value) {
+    if (value === null)
+        return null;
+    const enumKey = enumObject[String(value)];
+    return typeof enumKey === "string" && enumKey.length > 0 ? enumKey : null;
+}
+function parsePlayingCardEnumKey(enumKey) {
+    const match = /^([CDHS])(10|[2-9JQKA])$/.exec(enumKey);
+    if (!match)
+        return null;
+    const suitMap = {
+        C: "Clubs",
+        D: "Diamonds",
+        H: "Hearts",
+        S: "Spades",
+    };
+    const rankMap = {
+        J: "Jack",
+        Q: "Queen",
+        K: "King",
+        A: "Ace",
+    };
+    return {
+        rank: rankMap[match[2]] ?? match[2],
+        suit: suitMap[match[1]],
+    };
+}
+function rankNameFromEnum(enumKey) {
+    if (!enumKey)
+        return null;
+    const rankMap = {
+        Two: "2",
+        Three: "3",
+        Four: "4",
+        Five: "5",
+        Six: "6",
+        Seven: "7",
+        Eight: "8",
+        Nine: "9",
+        Ten: "10",
+        Jack: "Jack",
+        Queen: "Queen",
+        King: "King",
+        Ace: "Ace",
+    };
+    return rankMap[enumKey] ?? null;
+}
+function resolvePackedValue(input) {
+    if (typeof input === "number")
+        return Number.isFinite(input) ? input : null;
+    const runtimeItem = asRuntimeItem(input);
+    return finiteNumber(runtimeItem?.value);
+}
+function resolveEditionValue(input) {
+    const runtimeItem = asRuntimeItem(input);
+    const direct = finiteNumber(runtimeItem?.edition);
+    if (direct !== null)
+        return direct;
+    const packedValue = resolvePackedValue(input);
+    return packedValue !== null ? packedValue & VALUE_EDITION_MASK : null;
+}
+function resolveSealValue(input) {
+    const runtimeItem = asRuntimeItem(input);
+    const direct = finiteNumber(runtimeItem?.seal);
+    if (direct !== null)
+        return direct;
+    const packedValue = resolvePackedValue(input);
+    return packedValue !== null ? packedValue & VALUE_SEAL_MASK : null;
+}
+function resolveEnhancementValue(input) {
+    const runtimeItem = asRuntimeItem(input);
+    const direct = finiteNumber(runtimeItem?.enhancement);
+    if (direct !== null)
+        return direct;
+    const packedValue = resolvePackedValue(input);
+    return packedValue !== null ? packedValue & VALUE_ENHANCEMENT_MASK : null;
+}
+export function resolveMotelyItemType(input) {
+    if (typeof input === "number")
+        return Number.isFinite(input) ? (input & VALUE_TYPE_MASK) : null;
+    const runtimeItem = asRuntimeItem(input);
+    const directType = finiteNumber(runtimeItem?.type);
+    if (directType !== null)
+        return directType & VALUE_TYPE_MASK;
+    const packedValue = finiteNumber(runtimeItem?.value);
+    return packedValue !== null ? packedValue & VALUE_TYPE_MASK : null;
+}
+export function motelyItemRenderCategory(input) {
+    const enumKey = motelyItemTypeName(input);
+    return enumKey === "Unknown" ? "unknown" : getItemCategory(enumKey);
+}
+export function motelyItemEditionName(input) {
+    const enumKey = runtimeEnumName(Motely.MotelyItemEdition, resolveEditionValue(input));
+    return enumKey === null || enumKey === "None" ? null : enumKey;
+}
+export function motelyItemSealName(input) {
+    const enumKey = runtimeEnumName(Motely.MotelyItemSeal, resolveSealValue(input));
+    return enumKey === null || enumKey === "None" ? null : enumKey;
+}
+export function motelyItemEnhancementName(input) {
+    const enumKey = runtimeEnumName(Motely.MotelyItemEnhancement, resolveEnhancementValue(input));
+    return enumKey === null || enumKey === "None" ? null : enumKey;
+}
+export function motelyPlayingCardSuitName(input) {
+    const runtimeItem = asRuntimeItem(input);
+    const directSuit = runtimeEnumName(Motely.MotelyPlayingCardSuit, finiteNumber(runtimeItem?.suit));
+    if (directSuit === "Clubs" || directSuit === "Diamonds" || directSuit === "Hearts" || directSuit === "Spades") {
+        return directSuit;
+    }
+    const parsed = parsePlayingCardEnumKey(motelyItemTypeName(input));
+    return parsed?.suit ?? null;
+}
+export function motelyPlayingCardRankName(input) {
+    const runtimeItem = asRuntimeItem(input);
+    const directRank = runtimeEnumName(Motely.MotelyPlayingCardRank, finiteNumber(runtimeItem?.rank));
+    const normalizedDirect = rankNameFromEnum(directRank);
+    if (normalizedDirect !== null)
+        return normalizedDirect;
+    const parsed = parsePlayingCardEnumKey(motelyItemTypeName(input));
+    return parsed?.rank ?? null;
+}
 /** Get the enum key name for a MotelyItemType value. */
-export function motelyItemTypeName(itemType) {
+export function motelyItemTypeName(input) {
+    const itemType = resolveMotelyItemType(input);
+    if (itemType === null)
+        return "Unknown";
     ensureItemTypeMap();
     return _itemTypeToName.get(itemType) ?? "Unknown";
 }
 /** Get the category string for a MotelyItemType value. */
-export function motelyItemCategory(itemType) {
+export function motelyItemCategory(input) {
+    const itemType = resolveMotelyItemType(input);
+    if (itemType === null)
+        return "Unknown";
+    const renderCategory = motelyItemRenderCategory(itemType);
+    if (renderCategory === "playing")
+        return "Playing Card";
+    if (renderCategory === "spectral")
+        return "Spectral";
+    if (renderCategory === "tarot")
+        return "Tarot";
+    if (renderCategory === "planet")
+        return "Planet";
+    if (renderCategory === "joker")
+        return "Joker";
     return CATEGORY_TO_TYPE[itemType & CATEGORY_MASK] ?? "Unknown";
 }
 /** Convert PascalCase enum key to display name. */
-export function motelyItemDisplayName(itemType) {
-    const name = motelyItemTypeName(itemType);
-    return name.replace(/([a-z])([A-Z])/g, "$1 $2");
+export function motelyItemDisplayName(input) {
+    const enumKey = motelyItemTypeName(input);
+    return enumKey === "Unknown" ? "Unknown" : getItemDisplayName(enumKey);
 }
 // ─── Module-level cache ──────────────────────────────────────────────────────
 const _cache = new Map();
+const _decodedBaseCache = new Map();
+export function decodeMotelyItem(input) {
+    const itemType = resolveMotelyItemType(input);
+    if (itemType === null)
+        return null;
+    let base = _decodedBaseCache.get(itemType) ?? null;
+    if (!_decodedBaseCache.has(itemType)) {
+        const enumKey = motelyItemTypeName(itemType);
+        if (enumKey === "Unknown") {
+            _decodedBaseCache.set(itemType, null);
+            return null;
+        }
+        const category = motelyItemRenderCategory(itemType);
+        const rank = motelyPlayingCardRankName(itemType);
+        const suit = motelyPlayingCardSuitName(itemType);
+        base = {
+            itemType,
+            enumKey,
+            displayName: category === "playing" && rank && suit ? `${rank} of ${suit}` : getItemDisplayName(enumKey),
+            category,
+            rank,
+            suit,
+        };
+        _decodedBaseCache.set(itemType, base);
+    }
+    if (!base)
+        return null;
+    const decoded = {
+        ...base,
+        edition: motelyItemEditionName(input),
+        seal: motelyItemSealName(input),
+        enhancement: motelyItemEnhancementName(input),
+    };
+    return decoded;
+}
+export function decodeMotelyItemToJamlCard(input, scale = 1) {
+    const decoded = decodeMotelyItem(input);
+    if (!decoded || decoded.category === "unknown")
+        return null;
+    if (decoded.category === "playing") {
+        if (!decoded.rank || !decoded.suit)
+            return null;
+        return {
+            type: "playing",
+            card: {
+                name: `${decoded.rank} of ${decoded.suit}`,
+                edition: decoded.edition ?? undefined,
+                seal: decoded.seal ? `${decoded.seal} Seal` : undefined,
+                enhancements: decoded.enhancement ? [decoded.enhancement] : undefined,
+                rank: decoded.rank,
+                suit: decoded.suit,
+                scale,
+            },
+        };
+    }
+    return {
+        type: decoded.category === "joker" ? "joker" : "consumable",
+        card: {
+            name: decoded.displayName,
+            edition: decoded.edition ?? undefined,
+            scale,
+        },
+    };
+}
 /**
  * Decode a MotelyItemType integer to a display name for sprite lookup.
  * Cached per value.
  */
-export function decodeMotelyItemName(itemType) {
+export function decodeMotelyItemName(input) {
+    const itemType = resolveMotelyItemType(input);
+    if (itemType === null)
+        return null;
     if (_cache.has(itemType))
         return _cache.get(itemType) ?? null;
     const category = motelyItemCategory(itemType);
@@ -56,14 +272,17 @@ export function decodeMotelyItemName(itemType) {
         _cache.set(itemType, null);
         return null;
     }
-    const name = motelyItemDisplayName(itemType);
+    const decoded = decodeMotelyItem(input);
+    const name = decoded?.displayName ?? motelyItemDisplayName(itemType);
     _cache.set(itemType, name);
     return name;
 }
 /** Warm the cache for a batch of item type values. */
 export function warmMotelyItemCache(itemTypes) {
-    for (const t of itemTypes)
+    for (const t of itemTypes) {
         decodeMotelyItemName(t);
+        decodeMotelyItem(t);
+    }
 }
 /** Number of unique items decoded so far. */
 export function motelyItemCacheSize() {

package/dist/motely.d.ts

@@ -1 +1 @@
-export { motelyItemTypeName, motelyItemCategory, motelyItemDisplayName, decodeMotelyItemName, warmMotelyItemCache, motelyItemCacheSize, } from "./decode/motelyItemDecoder.js";
+export { decodeMotelyItem, decodeMotelyItemToJamlCard, motelyItemTypeName, motelyItemCategory, motelyItemDisplayName, motelyItemRenderCategory, motelyItemEditionName, motelyItemSealName, motelyItemEnhancementName, motelyPlayingCardRankName, motelyPlayingCardSuitName, decodeMotelyItemName, resolveMotelyItemType, warmMotelyItemCache, motelyItemCacheSize, type DecodedMotelyItem, type MotelyItemInput, type MotelyJamlCard, type MotelyRenderableCategory, type MotelyRuntimeItem, } from "./decode/motelyItemDecoder.js";

package/dist/motely.js

@@ -1,2 +1,2 @@
 "use client";
-export { motelyItemTypeName, motelyItemCategory, motelyItemDisplayName, decodeMotelyItemName, warmMotelyItemCache, motelyItemCacheSize, } from "./decode/motelyItemDecoder.js";
+export { decodeMotelyItem, decodeMotelyItemToJamlCard, motelyItemTypeName, motelyItemCategory, motelyItemDisplayName, motelyItemRenderCategory, motelyItemEditionName, motelyItemSealName, motelyItemEnhancementName, motelyPlayingCardRankName, motelyPlayingCardSuitName, decodeMotelyItemName, resolveMotelyItemType, warmMotelyItemCache, motelyItemCacheSize, } from "./decode/motelyItemDecoder.js";

package/dist/r3f/BalatroJokerMesh3D.d.ts

@@ -0,0 +1,8 @@
+export interface BalatroJokerMesh3DProps {
+    displayName: string;
+    onAtlasOk?: () => void;
+    onAtlasMissing?: () => void;
+    /** Override joker sheet URL (default: resolveJamlAssetUrl("jokers")). */
+    jokersImageUrl?: string;
+}
+export declare function BalatroJokerMesh3D({ displayName, onAtlasOk, onAtlasMissing, jokersImageUrl, }: BalatroJokerMesh3DProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/r3f/BalatroJokerMesh3D.js

@@ -0,0 +1,98 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useFrame } from "@react-three/fiber";
+import * as THREE from "three";
+import { applyBalatroGridUV, getLoadedTexturePixelSize } from "./gridUV.js";
+import { findJokerByDisplayName, getJokerAtlasGridSize, getJokerAtlasImageUrl, } from "./jokerRegistry.js";
+import { createZeroMagneticTarget, resetMagneticTarget } from "./magneticTilt.js";
+import { jokerAmbientTiltAtTime, jokerPointerTiltFromUv, JOKER_TILT_LERP_IN, JOKER_TILT_LERP_OUT, stableIdFraction, } from "./jokerTilt.js";
+export function BalatroJokerMesh3D({ displayName, onAtlasOk, onAtlasMissing, jokersImageUrl, }) {
+    const center = useMemo(() => findJokerByDisplayName(displayName), [displayName]);
+    const grid = useMemo(() => getJokerAtlasGridSize(), []);
+    const atlasUrl = jokersImageUrl ?? getJokerAtlasImageUrl();
+    const tiltGroupRef = useRef(null);
+    const magneticTarget = useRef(createZeroMagneticTarget());
+    const [map, setMap] = useState(null);
+    const [hovered, setHovered] = useState(false);
+    const loadSerial = useRef(0);
+    const idFrac = useMemo(() => stableIdFraction(displayName), [displayName]);
+    useEffect(() => {
+        if (!center)
+            return;
+        const serial = ++loadSerial.current;
+        let cancelled = false;
+        let loadedTex = null;
+        const loader = new THREE.TextureLoader();
+        loader.load(atlasUrl, (tex) => {
+            if (cancelled || serial !== loadSerial.current) {
+                tex.dispose();
+                return;
+            }
+            loadedTex = tex;
+            tex.colorSpace = THREE.SRGBColorSpace;
+            tex.magFilter = THREE.NearestFilter;
+            tex.minFilter = THREE.NearestFilter;
+            const { width: tw, height: th } = getLoadedTexturePixelSize(tex.image);
+            const cellW = tw / grid.cols;
+            const cellH = th / grid.rows;
+            applyBalatroGridUV(tex, center.pos, {
+                cellW,
+                cellH,
+                textureWidth: tw,
+                textureHeight: th,
+            });
+            setMap(tex);
+            onAtlasOk?.();
+        }, undefined, () => {
+            if (!cancelled && serial === loadSerial.current) {
+                setMap(null);
+                onAtlasMissing?.();
+            }
+        });
+        return () => {
+            cancelled = true;
+            loadedTex?.dispose();
+            setMap(null);
+        };
+    }, [center, displayName, grid.cols, grid.rows, atlasUrl, onAtlasMissing, onAtlasOk]);
+    useFrame((state, dt) => {
+        const g = tiltGroupRef.current;
+        if (!g)
+            return;
+        if (!hovered) {
+            jokerAmbientTiltAtTime(state.clock.elapsedTime, idFrac, magneticTarget.current);
+        }
+        const tr = magneticTarget.current;
+        const a = 1 - Math.exp(-(hovered ? JOKER_TILT_LERP_IN : JOKER_TILT_LERP_OUT) * dt);
+        g.rotation.x = THREE.MathUtils.lerp(g.rotation.x, tr.rx, a);
+        g.rotation.y = THREE.MathUtils.lerp(g.rotation.y, tr.ry, a);
+        g.rotation.z = THREE.MathUtils.lerp(g.rotation.z, tr.rz, a);
+        g.position.x = THREE.MathUtils.lerp(g.position.x, tr.ox, a);
+        g.position.y = THREE.MathUtils.lerp(g.position.y, tr.oy, a);
+    });
+    if (!center || !map)
+        return null;
+    const { width: tw, height: th } = getLoadedTexturePixelSize(map.image);
+    const cellW = tw / grid.cols;
+    const cellH = th / grid.rows;
+    const aspect = cellW / cellH;
+    const h = 2.4;
+    const w = aspect * h;
+    return (_jsx("group", { ref: tiltGroupRef, children: _jsxs("mesh", { onPointerMove: (e) => {
+                e.stopPropagation();
+                const uv = e.uv;
+                if (!uv)
+                    return;
+                jokerPointerTiltFromUv(uv, magneticTarget.current);
+            }, onPointerEnter: (e) => {
+                e.stopPropagation();
+                setHovered(true);
+                document.body.style.cursor = "pointer";
+            }, onPointerLeave: (e) => {
+                e.stopPropagation();
+                setHovered(false);
+                resetMagneticTarget(magneticTarget.current);
+                document.body.style.cursor = "auto";
+            }, children: [_jsx("planeGeometry", { args: [w, h] }), _jsx("meshBasicMaterial", { map: map, transparent: true, toneMapped: false })] }) }));
+}

package/dist/r3f/BalatroJokerPreview3D.d.ts

@@ -0,0 +1,14 @@
+import type { CSSProperties } from "react";
+export interface BalatroJokerPreview3DProps {
+    displayName: string;
+    className?: string;
+    style?: CSSProperties;
+    canvasHeight?: number;
+    jokersImageUrl?: string;
+}
+/**
+ * Self-contained Canvas + joker plane with magnetic tilt (for classifier / tool previews).
+ */
+export declare function BalatroJokerPreview3D({ displayName, className, style, canvasHeight, jokersImageUrl, }: BalatroJokerPreview3DProps): import("react/jsx-runtime").JSX.Element;
+/** @deprecated Use {@link BalatroJokerPreview3D}; kept for existing imports. */
+export declare const BalatroJokerThreePreview: typeof BalatroJokerPreview3D;

package/dist/r3f/BalatroJokerPreview3D.js

@@ -0,0 +1,30 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { Canvas } from "@react-three/fiber";
+import { Suspense, useMemo, useState } from "react";
+import { findJokerByDisplayName, getJokerAtlasGridSize } from "./jokerRegistry.js";
+import { BalatroJokerMesh3D } from "./BalatroJokerMesh3D.js";
+/**
+ * Self-contained Canvas + joker plane with magnetic tilt (for classifier / tool previews).
+ */
+export function BalatroJokerPreview3D({ displayName, className, style, canvasHeight = 272, jokersImageUrl, }) {
+    const center = useMemo(() => findJokerByDisplayName(displayName), [displayName]);
+    const grid = useMemo(() => getJokerAtlasGridSize(), []);
+    const [atlasMissing, setAtlasMissing] = useState(false);
+    const onOk = useMemo(() => () => setAtlasMissing(false), []);
+    const onMissing = useMemo(() => () => setAtlasMissing(true), []);
+    if (!center) {
+        return (_jsx("div", { className: className, style: style, children: _jsxs("div", { style: { color: "#555", fontSize: 11, padding: 8 }, children: ["No P_CENTERS match for \u201C", displayName, "\u201D. Align the row name with the in-game joker name or add an alias in jaml-ui joker registry data."] }) }));
+    }
+    return (_jsxs("div", { className: className, style: style, children: [_jsx("div", { style: {
+                    width: "100%",
+                    height: 300,
+                    padding: "14px 20px",
+                    boxSizing: "border-box",
+                    borderRadius: 6,
+                    overflow: "visible",
+                    background: "#0a0a0a",
+                }, children: _jsxs(Canvas, { camera: { position: [0, 0, 3.2], fov: 45 }, gl: { alpha: true, antialias: true }, style: { width: "100%", height: canvasHeight, touchAction: "none", display: "block" }, children: [_jsx("ambientLight", { intensity: 0.6 }), _jsx(Suspense, { fallback: null, children: _jsx(BalatroJokerMesh3D, { displayName: displayName, onAtlasOk: onOk, onAtlasMissing: onMissing, jokersImageUrl: jokersImageUrl }) })] }) }), atlasMissing ? (_jsxs("div", { style: { color: "#886644", fontSize: 11, lineHeight: 1.45, marginTop: 8 }, children: ["Add ", _jsx("strong", { children: "Jokers.png" }), " to your public assets or call", " ", _jsx("code", { style: { color: "#aaa" }, children: "setJamlAssetBaseUrl" }), " so", " ", _jsx("code", { style: { color: "#aaa" }, children: "resolveJamlAssetUrl(\"jokers\")" }), " loads. Key", " ", _jsx("code", { style: { color: "#aaa" }, children: center.key }), " \u2192 grid (", center.pos.x, ",", center.pos.y, "); sheet grid ", grid.cols, "\u00D7", grid.rows, "."] })) : null, _jsxs("p", { style: { fontSize: 10, color: "#444", marginTop: 8, marginBottom: 0 }, children: ["UVs from bundled ", _jsx("code", { style: { color: "#555" }, children: "balatro-jokers.json" }), " (grid cells) \u00B7 magnetic tilt approximates Balatro card/sprite hover behavior."] })] }));
+}
+/** @deprecated Use {@link BalatroJokerPreview3D}; kept for existing imports. */
+export const BalatroJokerThreePreview = BalatroJokerPreview3D;

package/dist/r3f/BalatroPlayingCard3D.d.ts

@@ -0,0 +1,22 @@
+import { type CardBoxOptions, type CardMagnetOptions } from "./cardConstants.js";
+import type { PlayingCard3DModel } from "./playingCardTypes.js";
+export interface BalatroPlayingCard3DProps {
+    card: PlayingCard3DModel;
+    position?: [number, number, number];
+    rotation?: [number, number, number];
+    selected?: boolean;
+    highlighted?: boolean;
+    onClick?: () => void;
+    onPointerEnter?: () => void;
+    onPointerLeave?: () => void;
+    /** Reserved for future flip animation */
+    faceDown?: boolean;
+    magnet?: CardMagnetOptions;
+    box?: CardBoxOptions;
+    /** Extra idle phase for subtle sway (e.g. hand index). */
+    idlePhase?: number;
+    deckUrl?: string;
+    enhancersUrl?: string;
+}
+export declare const BalatroPlayingCard3D: import("react").NamedExoticComponent<BalatroPlayingCard3DProps>;
+export default BalatroPlayingCard3D;

package/dist/r3f/BalatroPlayingCard3D.js

@@ -0,0 +1,62 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { memo, useMemo, useRef, useState } from "react";
+import { useFrame } from "@react-three/fiber";
+import { useSpring, animated } from "@react-spring/three";
+import { DEFAULT_CARD_BOX, DEFAULT_CARD_MAGNET } from "./cardConstants.js";
+import { createZeroMagneticTarget, lerpMagneticGroup, magneticTargetFromUvPlayingCard, resetMagneticTarget, } from "./magneticTilt.js";
+import { editionMaterialProps, enhancementGlowHex, sealColorHex } from "./playingCardVisuals.js";
+import { useCardBackTexture, usePlayingCardFaceTexture } from "./usePlayingCardTexture.js";
+export const BalatroPlayingCard3D = memo(function BalatroPlayingCard3D({ card, position = [0, 0, 0], rotation = [0, 0, 0], selected = false, highlighted = false, onClick, onPointerEnter, onPointerLeave, faceDown: _faceDown = false, magnet: magnetOverrides, box: boxOverrides, idlePhase = 0, deckUrl, enhancersUrl, }) {
+    const magnet = { ...DEFAULT_CARD_MAGNET, ...magnetOverrides };
+    const box = { ...DEFAULT_CARD_BOX, ...boxOverrides };
+    const tiltGroupRef = useRef(null);
+    const magneticTarget = useRef(createZeroMagneticTarget());
+    const [hovered, setHovered] = useState(false);
+    const cardTexture = usePlayingCardFaceTexture(card.suit, card.rank, { deckUrl, enhancersUrl });
+    const backTexture = useCardBackTexture();
+    const { posY, scale, glowIntensity } = useSpring({
+        posY: selected ? 0.3 : hovered ? 0.15 : 0,
+        scale: hovered ? 1.08 : selected ? 1.05 : 1,
+        glowIntensity: highlighted ? 1 : hovered ? 0.5 : 0,
+        config: { tension: 300, friction: 20 },
+    });
+    useFrame((state, dt) => {
+        const g = tiltGroupRef.current;
+        if (!g)
+            return;
+        const idleZ = Math.sin(state.clock.elapsedTime * 0.55 + position[0] * 2.1 + idlePhase) * 0.018;
+        lerpMagneticGroup(g, magneticTarget.current, dt, magnet.LERP_IN, magnet.LERP_OUT, hovered, idleZ);
+    });
+    const editionProps = useMemo(() => editionMaterialProps(card.edition), [card.edition]);
+    const enhancementColor = useMemo(() => enhancementGlowHex(card, highlighted), [card, highlighted]);
+    const onCardPointerMove = (e) => {
+        e.stopPropagation();
+        const uv = e.uv;
+        if (!uv)
+            return;
+        Object.assign(magneticTarget.current, magneticTargetFromUvPlayingCard(uv, magnet));
+    };
+    const onLeave = (e) => {
+        e.stopPropagation();
+        setHovered(false);
+        resetMagneticTarget(magneticTarget.current);
+        onPointerLeave?.();
+        document.body.style.cursor = "auto";
+    };
+    if (!cardTexture)
+        return null;
+    return (_jsx(animated.group, { "position-x": position[0], "position-y": posY.to((y) => position[1] + y), "position-z": position[2], "rotation-x": rotation[0], "rotation-y": rotation[1], "rotation-z": rotation[2], scale: scale, children: _jsxs("group", { ref: tiltGroupRef, children: [_jsx(animated.pointLight, { color: enhancementColor, intensity: glowIntensity.to((i) => i * 2), distance: 1, position: [0, 0, 0.1] }), _jsxs("mesh", { onClick: (e) => {
+                        e.stopPropagation();
+                        const hit = e.intersections[0];
+                        if (!hit || hit.object !== e.object)
+                            return;
+                        onClick?.();
+                    }, onPointerMove: onCardPointerMove, onPointerEnter: (e) => {
+                        e.stopPropagation();
+                        setHovered(true);
+                        onPointerEnter?.();
+                        document.body.style.cursor = "pointer";
+                    }, onPointerLeave: onLeave, castShadow: true, receiveShadow: true, children: [_jsx("boxGeometry", { args: [box.WIDTH, box.HEIGHT, box.DEPTH] }), _jsx("meshBasicMaterial", { attach: "material-4", map: cardTexture, toneMapped: false }), _jsx("meshStandardMaterial", { attach: "material-5", map: backTexture, ...editionProps }), _jsx("meshStandardMaterial", { attach: "material-0", color: "#f5f5dc" }), _jsx("meshStandardMaterial", { attach: "material-1", color: "#f5f5dc" }), _jsx("meshStandardMaterial", { attach: "material-2", color: "#f5f5dc" }), _jsx("meshStandardMaterial", { attach: "material-3", color: "#f5f5dc" })] }), selected ? (_jsxs("mesh", { position: [0, 0, -box.DEPTH], children: [_jsx("ringGeometry", { args: [0.45, 0.5, 32] }), _jsx("meshBasicMaterial", { color: "#f1c40f", transparent: true, opacity: 0.8 })] })) : null, card.enhancement ? (_jsxs("mesh", { position: [box.WIDTH / 2 - 0.1, box.HEIGHT / 2 - 0.1, box.DEPTH + 0.01], children: [_jsx("circleGeometry", { args: [0.08, 16] }), _jsx("meshBasicMaterial", { color: enhancementColor })] })) : null, card.seal ? (_jsxs("mesh", { position: [-box.WIDTH / 2 + 0.1, -box.HEIGHT / 2 + 0.1, box.DEPTH + 0.01], children: [_jsx("circleGeometry", { args: [0.06, 6] }), _jsx("meshBasicMaterial", { color: sealColorHex(card.seal) })] })) : null] }) }));
+});
+export default BalatroPlayingCard3D;

package/dist/r3f/cardConstants.d.ts

@@ -0,0 +1,16 @@
+/** Default magnetic tilt / parallax matching Balatro-style card hover. */
+export declare const DEFAULT_CARD_MAGNET: {
+    readonly MAX_TILT_X: 0.36;
+    readonly MAX_TILT_Y: 0.42;
+    readonly MAX_SHIFT: 0.038;
+    readonly TWIST_Z: 0.11;
+    readonly LERP_IN: 18;
+    readonly LERP_OUT: 10;
+};
+export type CardMagnetOptions = Partial<typeof DEFAULT_CARD_MAGNET>;
+export declare const DEFAULT_CARD_BOX: {
+    readonly WIDTH: 0.7;
+    readonly HEIGHT: 0.95;
+    readonly DEPTH: 0.02;
+};
+export type CardBoxOptions = Partial<typeof DEFAULT_CARD_BOX>;

package/dist/r3f/cardConstants.js

@@ -0,0 +1,14 @@
+/** Default magnetic tilt / parallax matching Balatro-style card hover. */
+export const DEFAULT_CARD_MAGNET = {
+    MAX_TILT_X: 0.36,
+    MAX_TILT_Y: 0.42,
+    MAX_SHIFT: 0.038,
+    TWIST_Z: 0.11,
+    LERP_IN: 18,
+    LERP_OUT: 10,
+};
+export const DEFAULT_CARD_BOX = {
+    WIDTH: 0.7,
+    HEIGHT: 0.95,
+    DEPTH: 0.02,
+};

package/dist/r3f/compositedAtlas.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Composite transparent 8Bit deck pips onto Enhancers card fronts (per-cell).
+ * Output canvas matches atlas pixel size so UV math is unchanged.
+ */
+export declare function loadCompositedPlayingAtlas(atlasUrl: string, cols: number, rows: number, enhancersUrl?: string): Promise<HTMLCanvasElement>;