@jgengine/core 0.11.0 → 0.13.0

package/dist/devtools/urlFlags.js

@@ -0,0 +1,62 @@
+/**
+ * URL-backed debug flags — the single seam hosts use to mirror an engine debug surface (the scene
+ * editor, the devtools overlay) into the page query string. Mirroring means the URL is the honest
+ * record of what is open: share it to reproduce the state, and strip the param (then reload) to get
+ * a clean game with the surface gone. All functions no-op safely off the main browser thread.
+ */
+/** Values that read as "off" when a param is present but disabled — `?debug=0` stays closed. */
+const FALSY = new Set(["", "0", "false", "off", "no"]);
+/** The live browser window, or null when there is no DOM (SSR, tests, worker). */
+function browserWindow() {
+    const candidate = globalThis.window;
+    if (candidate === undefined || candidate.location === undefined || candidate.history === undefined) {
+        return null;
+    }
+    return candidate;
+}
+/** The current query value of `param`, or null when absent (or no DOM). */
+export function readUrlParam(param) {
+    const win = browserWindow();
+    if (win === null)
+        return null;
+    return new URLSearchParams(win.location.search).get(param);
+}
+/** True when `param` is present and not an explicit off value (`0`/`false`/`off`/`no`). */
+export function readUrlFlag(param) {
+    const value = readUrlParam(param);
+    return value !== null && !FALSY.has(value.toLowerCase());
+}
+/**
+ * Sets `param` to `value`, or removes it when `value` is null, rewriting the URL in place with
+ * `history.replaceState` so the rest of the query and the hash survive and no history entry is
+ * pushed. No-ops without a DOM, and skips the write when the URL already matches.
+ */
+export function writeUrlParam(param, value) {
+    const win = browserWindow();
+    if (win === null)
+        return;
+    const url = new URL(win.location.href);
+    if (value === null) {
+        if (!url.searchParams.has(param))
+            return;
+        url.searchParams.delete(param);
+    }
+    else {
+        if (url.searchParams.get(param) === value)
+            return;
+        url.searchParams.set(param, value);
+    }
+    win.history.replaceState(win.history.state, "", url.toString());
+}
+/**
+ * Fires `listener` whenever the query string may have changed out from under a flag — browser
+ * back/forward (`popstate`). Manual address-bar edits reload the page, so initial reads cover
+ * those; this keeps in-app state honest across history navigation. Returns an unsubscribe.
+ */
+export function subscribeUrlChange(listener) {
+    const win = browserWindow();
+    if (win === null)
+        return () => { };
+    win.addEventListener("popstate", listener);
+    return () => win.removeEventListener("popstate", listener);
+}

package/dist/economy/auctionBook.d.ts

@@ -0,0 +1,122 @@
+import type { CollectionBoxSnapshot } from "./listingBook.js";
+/** One live timed auction in an {@link AuctionBook}: an item stack under open bidding until it closes. */
+export interface Auction {
+    readonly id: string;
+    readonly sellerId: string;
+    readonly itemId: string;
+    readonly count: number;
+    readonly currency: string;
+    readonly startPrice: number;
+    readonly minIncrement: number;
+    readonly buyoutPrice: number | null;
+    readonly listedAt: number;
+    readonly endsAt: number;
+    readonly highBid: HighBid | null;
+}
+/** The current leading bid on an {@link Auction}. */
+export interface HighBid {
+    readonly bidderId: string;
+    readonly amount: number;
+    readonly at: number;
+}
+/**
+ * Tunables for {@link createAuctionBook} — per-seller auction cap, run length, house cut, and the
+ * anti-snipe window: a bid landing within `antiSnipeWindowSeconds` of the close pushes the close
+ * out so it ends at least `antiSnipeExtensionSeconds` after that bid.
+ */
+export interface AuctionBookConfig {
+    maxAuctionsPerSeller: number;
+    durationSeconds: number;
+    cutRate: number;
+    antiSnipeWindowSeconds?: number;
+    antiSnipeExtensionSeconds?: number;
+}
+/** Input to {@link AuctionBook.post} — the goods, opening terms, and current game-time. */
+export interface PostAuctionInput {
+    id?: string;
+    sellerId: string;
+    itemId: string;
+    count: number;
+    currency: string;
+    startPrice: number;
+    minIncrement: number;
+    buyoutPrice?: number;
+    now: number;
+}
+/** Why {@link AuctionBook.post} refused an auction. */
+export type PostAuctionReason = "invalid-count" | "invalid-price" | "invalid-increment" | "invalid-buyout" | "auction-cap-reached";
+/** Result of {@link AuctionBook.post}. */
+export type PostAuctionResult = {
+    status: "ok";
+    auction: Auction;
+} | {
+    status: "rejected";
+    reason: PostAuctionReason;
+};
+/** Why {@link AuctionBook.bid} refused a bid. */
+export type BidReason = "not-found" | "ended" | "own-auction" | "already-leading" | "bid-too-low" | "invalid-amount" | "no-buyout";
+/**
+ * Result of {@link AuctionBook.bid}. On `ok` the caller must escrow `escrowed` from the bidder's
+ * wallet; any previously escrowed leading bid has already been refunded to that bidder's
+ * collection box. `won` is true when the bid met the buyout price and settled the auction
+ * immediately.
+ */
+export type BidResult = {
+    status: "ok";
+    auction: Auction;
+    escrowed: number;
+    won: boolean;
+} | {
+    status: "rejected";
+    reason: BidReason;
+};
+/** Result of {@link AuctionBook.cancel}: a bid-on auction can no longer be withdrawn. */
+export type CancelAuctionResult = {
+    status: "ok";
+    auction: Auction;
+} | {
+    status: "rejected";
+    reason: "not-found" | "not-owner" | "has-bids";
+};
+/** How one closed auction resolved during {@link AuctionBook.settleExpired}. */
+export type AuctionSettlement = {
+    status: "sold";
+    auction: Auction;
+    winnerId: string;
+    price: number;
+    houseCut: number;
+    sellerProceeds: number;
+} | {
+    status: "returned";
+    auction: Auction;
+};
+/**
+ * A timed-bid auction marketplace plus the per-player collection boxes behind it. See
+ * {@link createAuctionBook}.
+ */
+export interface AuctionBook {
+    post(input: PostAuctionInput): PostAuctionResult;
+    bid(auctionId: string, bidderId: string, amount: number, now: number): BidResult;
+    buyout(auctionId: string, buyerId: string, now: number): BidResult;
+    cancel(auctionId: string, sellerId: string): CancelAuctionResult;
+    settleExpired(now: number): readonly AuctionSettlement[];
+    get(auctionId: string): Auction | null;
+    active(): readonly Auction[];
+    auctionsOf(sellerId: string): readonly Auction[];
+    countOf(sellerId: string): number;
+    collectionOf(playerId: string): CollectionBoxSnapshot;
+    claimCurrency(playerId: string): Readonly<Record<string, number>>;
+    claimItem(playerId: string, itemId: string, count: number): boolean;
+}
+/**
+ * Timed-bid auctions in the WoW/BDO auction-house mold: post an item with a start price, minimum
+ * increment, and optional buyout; bids escrow currency, outbid players are refunded into their
+ * collection box, bids near the close extend it (anti-snipe), and settlement pays the seller minus
+ * the house cut while the item lands in the winner's collection box. Unsold auctions return the
+ * goods to the seller's box. Wallet and inventory movement is the caller's job (mirrors
+ * `economy/listingBook`) — this primitive owns the auction lifecycle and the escrowed
+ * collection-box bookkeeping behind it.
+ *
+ * @capability auction-book timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement
+ */
+export declare function createAuctionBook(config: AuctionBookConfig): AuctionBook;

package/dist/economy/auctionBook.js

@@ -0,0 +1,213 @@
+/**
+ * Timed-bid auctions in the WoW/BDO auction-house mold: post an item with a start price, minimum
+ * increment, and optional buyout; bids escrow currency, outbid players are refunded into their
+ * collection box, bids near the close extend it (anti-snipe), and settlement pays the seller minus
+ * the house cut while the item lands in the winner's collection box. Unsold auctions return the
+ * goods to the seller's box. Wallet and inventory movement is the caller's job (mirrors
+ * `economy/listingBook`) — this primitive owns the auction lifecycle and the escrowed
+ * collection-box bookkeeping behind it.
+ *
+ * @capability auction-book timed bid auctions with escrowed bids, buyout, anti-snipe close extension, and collection-box settlement
+ */
+export function createAuctionBook(config) {
+    const auctions = new Map();
+    const boxes = new Map();
+    let counter = 0;
+    function boxOf(playerId) {
+        let box = boxes.get(playerId);
+        if (box === undefined) {
+            box = { currency: {}, items: [] };
+            boxes.set(playerId, box);
+        }
+        return box;
+    }
+    function creditCurrency(playerId, currency, amount) {
+        const box = boxOf(playerId);
+        box.currency[currency] = (box.currency[currency] ?? 0) + amount;
+    }
+    function creditItem(playerId, itemId, count) {
+        const box = boxOf(playerId);
+        const existing = box.items.find((stack) => stack.itemId === itemId);
+        if (existing !== undefined)
+            existing.count += count;
+        else
+            box.items.push({ itemId, count });
+    }
+    function countOf(sellerId) {
+        let total = 0;
+        for (const auction of auctions.values())
+            if (auction.sellerId === sellerId)
+                total += 1;
+        return total;
+    }
+    function snapshot(state) {
+        return { ...state, highBid: state.highBid };
+    }
+    function minimumBid(state) {
+        return state.highBid === null ? state.startPrice : state.highBid.amount + state.minIncrement;
+    }
+    function settle(state, winnerId, price) {
+        auctions.delete(state.id);
+        const houseCut = Math.floor(price * config.cutRate);
+        const sellerProceeds = price - houseCut;
+        creditCurrency(state.sellerId, state.currency, sellerProceeds);
+        creditItem(winnerId, state.itemId, state.count);
+        return { status: "sold", auction: snapshot(state), winnerId, price, houseCut, sellerProceeds };
+    }
+    function acceptBid(state, bidderId, amount, now) {
+        if (state.highBid !== null) {
+            creditCurrency(state.highBid.bidderId, state.currency, state.highBid.amount);
+        }
+        if (state.buyoutPrice !== null && amount >= state.buyoutPrice) {
+            state.highBid = { bidderId, amount: state.buyoutPrice, at: now };
+            const settlement = settle(state, bidderId, state.buyoutPrice);
+            if (settlement.status !== "sold")
+                throw new Error("unreachable");
+            return { status: "ok", auction: settlement.auction, escrowed: state.buyoutPrice, won: true };
+        }
+        state.highBid = { bidderId, amount, at: now };
+        const window = config.antiSnipeWindowSeconds ?? 0;
+        const extension = config.antiSnipeExtensionSeconds ?? 0;
+        if (window > 0 && extension > 0 && state.endsAt - now < window) {
+            state.endsAt = Math.max(state.endsAt, now + extension);
+        }
+        return { status: "ok", auction: snapshot(state), escrowed: amount, won: false };
+    }
+    return {
+        post(input) {
+            if (!Number.isInteger(input.count) || input.count < 1) {
+                return { status: "rejected", reason: "invalid-count" };
+            }
+            if (!Number.isFinite(input.startPrice) || input.startPrice <= 0) {
+                return { status: "rejected", reason: "invalid-price" };
+            }
+            if (!Number.isFinite(input.minIncrement) || input.minIncrement <= 0) {
+                return { status: "rejected", reason: "invalid-increment" };
+            }
+            if (input.buyoutPrice !== undefined) {
+                if (!Number.isFinite(input.buyoutPrice) || input.buyoutPrice < input.startPrice) {
+                    return { status: "rejected", reason: "invalid-buyout" };
+                }
+            }
+            if (countOf(input.sellerId) >= config.maxAuctionsPerSeller) {
+                return { status: "rejected", reason: "auction-cap-reached" };
+            }
+            const id = input.id ?? `auction_${(counter += 1)}`;
+            const state = {
+                id,
+                sellerId: input.sellerId,
+                itemId: input.itemId,
+                count: input.count,
+                currency: input.currency,
+                startPrice: input.startPrice,
+                minIncrement: input.minIncrement,
+                buyoutPrice: input.buyoutPrice ?? null,
+                listedAt: input.now,
+                endsAt: input.now + config.durationSeconds,
+                highBid: null,
+            };
+            auctions.set(id, state);
+            return { status: "ok", auction: snapshot(state) };
+        },
+        bid(auctionId, bidderId, amount, now) {
+            const state = auctions.get(auctionId);
+            if (state === undefined)
+                return { status: "rejected", reason: "not-found" };
+            if (state.endsAt <= now)
+                return { status: "rejected", reason: "ended" };
+            if (state.sellerId === bidderId)
+                return { status: "rejected", reason: "own-auction" };
+            if (!Number.isFinite(amount) || amount <= 0) {
+                return { status: "rejected", reason: "invalid-amount" };
+            }
+            if (state.highBid?.bidderId === bidderId) {
+                return { status: "rejected", reason: "already-leading" };
+            }
+            if (amount < minimumBid(state))
+                return { status: "rejected", reason: "bid-too-low" };
+            return acceptBid(state, bidderId, amount, now);
+        },
+        buyout(auctionId, buyerId, now) {
+            const state = auctions.get(auctionId);
+            if (state === undefined)
+                return { status: "rejected", reason: "not-found" };
+            if (state.endsAt <= now)
+                return { status: "rejected", reason: "ended" };
+            if (state.sellerId === buyerId)
+                return { status: "rejected", reason: "own-auction" };
+            if (state.buyoutPrice === null)
+                return { status: "rejected", reason: "no-buyout" };
+            if (state.highBid?.bidderId === buyerId) {
+                creditCurrency(buyerId, state.currency, state.highBid.amount);
+                state.highBid = null;
+            }
+            return acceptBid(state, buyerId, state.buyoutPrice, now);
+        },
+        cancel(auctionId, sellerId) {
+            const state = auctions.get(auctionId);
+            if (state === undefined)
+                return { status: "rejected", reason: "not-found" };
+            if (state.sellerId !== sellerId)
+                return { status: "rejected", reason: "not-owner" };
+            if (state.highBid !== null)
+                return { status: "rejected", reason: "has-bids" };
+            auctions.delete(auctionId);
+            return { status: "ok", auction: snapshot(state) };
+        },
+        settleExpired(now) {
+            const ended = [];
+            for (const state of auctions.values())
+                if (state.endsAt <= now)
+                    ended.push(state);
+            const settlements = [];
+            for (const state of ended) {
+                if (state.highBid === null) {
+                    auctions.delete(state.id);
+                    creditItem(state.sellerId, state.itemId, state.count);
+                    settlements.push({ status: "returned", auction: snapshot(state) });
+                }
+                else {
+                    settlements.push(settle(state, state.highBid.bidderId, state.highBid.amount));
+                }
+            }
+            return settlements;
+        },
+        get(auctionId) {
+            const state = auctions.get(auctionId);
+            return state === undefined ? null : snapshot(state);
+        },
+        active() {
+            return [...auctions.values()].map(snapshot);
+        },
+        auctionsOf(sellerId) {
+            return [...auctions.values()].filter((a) => a.sellerId === sellerId).map(snapshot);
+        },
+        countOf,
+        collectionOf(playerId) {
+            const box = boxes.get(playerId);
+            if (box === undefined)
+                return { currency: {}, items: [] };
+            return { currency: { ...box.currency }, items: box.items.map((stack) => ({ ...stack })) };
+        },
+        claimCurrency(playerId) {
+            const box = boxOf(playerId);
+            const claimed = box.currency;
+            box.currency = {};
+            return claimed;
+        },
+        claimItem(playerId, itemId, count) {
+            const box = boxOf(playerId);
+            const index = box.items.findIndex((stack) => stack.itemId === itemId);
+            if (index === -1)
+                return false;
+            const stack = box.items[index];
+            if (stack.count < count)
+                return false;
+            if (stack.count === count)
+                box.items.splice(index, 1);
+            else
+                box.items[index] = { ...stack, count: stack.count - count };
+            return true;
+        },
+    };
+}

package/dist/economy/priceHistory.d.ts

@@ -0,0 +1,44 @@
+/** One completed sale recorded into a {@link PriceHistory}. */
+export interface SaleRecord {
+    readonly itemId: string;
+    readonly count: number;
+    readonly unitPrice: number;
+    readonly currency: string;
+    readonly at: number;
+}
+/**
+ * Tunables for {@link createPriceHistory} — the per-item sample cap bounds memory; the optional
+ * window drops samples older than `windowSeconds` whenever the history is written or read with a
+ * newer timestamp.
+ */
+export interface PriceHistoryConfig {
+    maxSamplesPerItem: number;
+    windowSeconds?: number;
+}
+/** Aggregated market stats for one item over the retained samples. */
+export interface PriceStats {
+    readonly sampleCount: number;
+    readonly volume: number;
+    readonly minUnitPrice: number;
+    readonly maxUnitPrice: number;
+    readonly averageUnitPrice: number;
+    readonly latestUnitPrice: number;
+}
+/** A bounded rolling record of completed sales per item. See {@link createPriceHistory}. */
+export interface PriceHistory {
+    record(sale: SaleRecord): void;
+    statsOf(itemId: string, now?: number): PriceStats | null;
+    samplesOf(itemId: string, now?: number): readonly SaleRecord[];
+    itemIds(): readonly string[];
+    clear(itemId?: string): void;
+}
+/**
+ * The "market price" readout behind every auction house: a bounded rolling record of completed
+ * sales per item, aggregated into min/max/volume-weighted-average/latest unit-price stats so games
+ * can show current value and recent trends. Memory is bounded by `maxSamplesPerItem` (oldest
+ * samples drop first) and optionally by a sliding time window; timestamps are injected by the
+ * caller so the history stays deterministic.
+ *
+ * @capability price-history rolling per-item sale records aggregated into market price stats
+ */
+export declare function createPriceHistory(config: PriceHistoryConfig): PriceHistory;

package/dist/economy/priceHistory.js

@@ -0,0 +1,89 @@
+/**
+ * The "market price" readout behind every auction house: a bounded rolling record of completed
+ * sales per item, aggregated into min/max/volume-weighted-average/latest unit-price stats so games
+ * can show current value and recent trends. Memory is bounded by `maxSamplesPerItem` (oldest
+ * samples drop first) and optionally by a sliding time window; timestamps are injected by the
+ * caller so the history stays deterministic.
+ *
+ * @capability price-history rolling per-item sale records aggregated into market price stats
+ */
+export function createPriceHistory(config) {
+    const samples = new Map();
+    function trim(list, now) {
+        if (config.windowSeconds !== undefined && now !== undefined) {
+            const cutoff = now - config.windowSeconds;
+            let drop = 0;
+            while (drop < list.length && list[drop].at < cutoff)
+                drop += 1;
+            if (drop > 0)
+                list.splice(0, drop);
+        }
+        if (list.length > config.maxSamplesPerItem) {
+            list.splice(0, list.length - config.maxSamplesPerItem);
+        }
+    }
+    function retained(itemId, now) {
+        const list = samples.get(itemId);
+        if (list === undefined)
+            return null;
+        trim(list, now);
+        if (list.length === 0) {
+            samples.delete(itemId);
+            return null;
+        }
+        return list;
+    }
+    return {
+        record(sale) {
+            if (!Number.isFinite(sale.unitPrice) || sale.unitPrice < 0)
+                return;
+            if (!Number.isInteger(sale.count) || sale.count < 1)
+                return;
+            let list = samples.get(sale.itemId);
+            if (list === undefined) {
+                list = [];
+                samples.set(sale.itemId, list);
+            }
+            list.push(sale);
+            trim(list, sale.at);
+        },
+        statsOf(itemId, now) {
+            const list = retained(itemId, now);
+            if (list === null)
+                return null;
+            let volume = 0;
+            let spend = 0;
+            let min = Number.POSITIVE_INFINITY;
+            let max = Number.NEGATIVE_INFINITY;
+            for (const sale of list) {
+                volume += sale.count;
+                spend += sale.unitPrice * sale.count;
+                if (sale.unitPrice < min)
+                    min = sale.unitPrice;
+                if (sale.unitPrice > max)
+                    max = sale.unitPrice;
+            }
+            return {
+                sampleCount: list.length,
+                volume,
+                minUnitPrice: min,
+                maxUnitPrice: max,
+                averageUnitPrice: spend / volume,
+                latestUnitPrice: list[list.length - 1].unitPrice,
+            };
+        },
+        samplesOf(itemId, now) {
+            const list = retained(itemId, now);
+            return list === null ? [] : [...list];
+        },
+        itemIds() {
+            return [...samples.keys()];
+        },
+        clear(itemId) {
+            if (itemId === undefined)
+                samples.clear();
+            else
+                samples.delete(itemId);
+        },
+    };
+}

package/dist/economy/unlockPoints.d.ts

@@ -0,0 +1,92 @@
+import { type Curve } from "../game/progression.js";
+/**
+ * Plain, JSON-serializable snapshot of a point pool. `earned` is the lifetime total ever
+ * banked; every committed unlock lives in `unlocked` as `id → cost paid`. `spent` and
+ * `available` are always derived (`spent = Σ unlocked`, `available = earned − spent`) so the
+ * two can never drift out of sync across a serialize/hydrate round-trip.
+ */
+export interface UnlockPointsState {
+    /** Total points ever granted; unaffected by spending, refunds, or respec. */
+    earned: number;
+    /** Committed unlocks as `unlockId → cost paid`. Sums to the currently spent total. */
+    unlocked: Readonly<Record<string, number>>;
+}
+/** Options for {@link UnlockPoints.spend}. */
+export interface SpendOptions {
+    /**
+     * Injected prerequisite gate, checked before any points are deducted. Return `false` to
+     * reject with `"missing-prerequisites"`. Compose with `economy/techTree` without coupling —
+     * e.g. `{ requires: () => techTree.canUnlock(userId, id).ok }` — or any game-defined rule.
+     */
+    requires?: () => boolean;
+}
+/** Why a {@link UnlockPoints.spend} was refused; the pool is left untouched on any rejection. */
+export type SpendRejection = "invalid-cost" | "already-unlocked" | "missing-prerequisites" | "insufficient-points";
+/** Result of {@link UnlockPoints.spend}: the new `available` balance on success, else a reason. */
+export type SpendResult = {
+    ok: true;
+    available: number;
+} | {
+    ok: false;
+    reason: SpendRejection;
+};
+/** Configuration for {@link createUnlockPoints}. */
+export interface UnlockPointsConfig {
+    /**
+     * Points granted for *reaching* a level, evaluated by {@link UnlockPoints.grantForLevel} and
+     * summed across gained levels by {@link UnlockPoints.grantOnLevelUp}. Non-uniform curves are
+     * fine (front-loaded, milestone `steps`, etc.). Defaults to one point per level.
+     */
+    perLevel?: Curve;
+    /** Points banked before any leveling — a starting unlock budget. Default `0`. */
+    start?: number;
+    /** Rehydrate from a prior {@link UnlockPoints.snapshot}. */
+    state?: UnlockPointsState;
+}
+/**
+ * A spendable unlock-point economy: a pool you earn (per level or by direct grant) and spend to
+ * unlock nodes, with per-unlock refunds and a full respec.
+ */
+export interface UnlockPoints {
+    /** Unspent points on hand (`earned − spent`). */
+    available(): number;
+    /** Lifetime points ever granted; never reduced by spending or respec. */
+    earned(): number;
+    /** Points currently committed to unlocks (`Σ` of every unlock cost). */
+    spent(): number;
+    /** Bank an arbitrary point grant (quest reward, difficulty bonus). Non-positive/non-finite is ignored. */
+    grant(amount: number): void;
+    /** Bank the `perLevel` grant for reaching `level`; returns the amount actually added. */
+    grantForLevel(level: number): number;
+    /** Bank grants for every level in `(fromLevel, toLevel]`; returns the total added. */
+    grantOnLevelUp(fromLevel: number, toLevel: number): number;
+    /** True when `available() >= cost`. */
+    canAfford(cost: number): boolean;
+    /** Deduct `cost` and record `unlockId`, unless rejected (see {@link SpendResult}). */
+    spend(unlockId: string, cost: number, opts?: SpendOptions): SpendResult;
+    /** True once `unlockId` has been spent on and not refunded. */
+    isUnlocked(id: string): boolean;
+    /** Points paid for `id`, or `0` if it is not unlocked. */
+    costOf(id: string): number;
+    /** Every currently unlocked id, in insertion order. */
+    unlockedIds(): string[];
+    /** Refund a single unlock, returning its cost to `available`. Returns `false` if not unlocked. */
+    refund(unlockId: string): boolean;
+    /** Mindwipe: refund every unlock and clear the recorded set, keeping `earned`. Returns points refunded. */
+    respec(): number;
+    /** Plain serializable snapshot; safe to `JSON.stringify` and later {@link hydrate}. */
+    snapshot(): UnlockPointsState;
+    /** Replace all state from a prior {@link snapshot}, discarding invalid entries. */
+    hydrate(state: UnlockPointsState): void;
+}
+/**
+ * Spendable unlock-point economy — the seam between leveling and a tech tree. Points are earned
+ * per level (via a configurable, possibly non-uniform grant curve) or granted directly, then
+ * spent to unlock nodes; spending can defer prerequisite checks to an injected predicate so it
+ * composes with `economy/techTree` (or any gate) without depending on it. Individual unlocks
+ * refund, and `respec` fully refunds a build while preserving lifetime earned points. All state
+ * is plain and JSON round-trips.
+ *
+ * @capability unlock-points spendable point pool earned per level and spent to unlock nodes, with refund and respec
+ */
+export declare function createUnlockPoints(config?: UnlockPointsConfig): UnlockPoints;