@jgengine/core 0.10.0 → 0.12.0

package/dist/economy/techTree.d.ts

@@ -19,11 +19,22 @@ export type TechCheck = {
 } | ({
     ok: false;
 } & TechRejection);
+/** @internal */
 export declare function techPrerequisitesMet(state: TechState, node: TechNodeDef): boolean;
+/** @internal */
 export declare function missingPrerequisites(state: TechState, node: TechNodeDef): string[];
+/** @internal */
 export declare function canUnlockTech(defs: readonly TechNodeDef[], state: TechState, id: string): TechCheck;
+/** @internal */
 export declare function grantTech(state: TechState, node: TechNodeDef): string[];
+/**
+ * Research/tech nodes gated by prerequisites that unlock recipes and capabilities as they are granted.
+ *
+ * @capability tech-tree research nodes with prerequisites that unlock recipes
+  * @internal
+  */
 export declare function availableTech(defs: readonly TechNodeDef[], state: TechState): TechNodeDef[];
+/** @internal */
 export declare function unlockedRecipes(defs: readonly TechNodeDef[], state: TechState): string[];
 export interface TechTree {
     has(userId: string, id: string): boolean;
@@ -37,4 +48,5 @@ export interface TechTree {
     snapshot(userId: string): string[];
     hydrate(userId: string, ids: string[]): void;
 }
+/** @internal */
 export declare function createTechTree(defs?: readonly TechNodeDef[]): TechTree;

package/dist/economy/techTree.js

@@ -1,11 +1,14 @@
 import { createUnlocks, grantUnlock, hasUnlock, unlockTree } from "../game/unlocks.js";
+/** @internal */
 export function techPrerequisitesMet(state, node) {
     const requires = node.requires ?? [];
     return requires.every((id) => hasUnlock(state, id));
 }
+/** @internal */
 export function missingPrerequisites(state, node) {
     return (node.requires ?? []).filter((id) => !hasUnlock(state, id));
 }
+/** @internal */
 export function canUnlockTech(defs, state, id) {
     const node = defs.find((n) => n.id === id);
     if (node === undefined)
@@ -17,15 +20,23 @@ export function canUnlockTech(defs, state, id) {
         return { ok: false, reason: "missing-prerequisites", missing };
     return { ok: true };
 }
+/** @internal */
 export function grantTech(state, node) {
     let next = grantUnlock(state, node.id);
     for (const extra of node.grants ?? [])
         next = grantUnlock(next, extra);
     return next;
 }
+/**
+ * Research/tech nodes gated by prerequisites that unlock recipes and capabilities as they are granted.
+ *
+ * @capability tech-tree research nodes with prerequisites that unlock recipes
+  * @internal
+  */
 export function availableTech(defs, state) {
     return defs.filter((node) => !hasUnlock(state, node.id) && techPrerequisitesMet(state, node));
 }
+/** @internal */
 export function unlockedRecipes(defs, state) {
     const recipes = [];
     for (const node of defs) {
@@ -34,6 +45,7 @@ export function unlockedRecipes(defs, state) {
     }
     return recipes;
 }
+/** @internal */
 export function createTechTree(defs = []) {
     const nodes = new Map();
     for (const def of defs)

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;

package/dist/economy/unlockPoints.js

@@ -0,0 +1,103 @@
+import { evalCurve } from "../game/progression.js";
+const DEFAULT_PER_LEVEL = { kind: "const", value: 1 };
+function sanitizeAmount(value) {
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * 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 function createUnlockPoints(config = {}) {
+    const perLevel = config.perLevel ?? DEFAULT_PER_LEVEL;
+    const unlocked = new Map();
+    let earned = 0;
+    const load = (state) => {
+        unlocked.clear();
+        earned = sanitizeAmount(state.earned);
+        for (const [id, cost] of Object.entries(state.unlocked)) {
+            const paid = Number.isFinite(cost) && cost >= 0 ? cost : 0;
+            unlocked.set(id, paid);
+        }
+    };
+    if (config.state !== undefined) {
+        load(config.state);
+    }
+    else {
+        earned = sanitizeAmount(config.start ?? 0);
+    }
+    const spentTotal = () => {
+        let total = 0;
+        for (const cost of unlocked.values())
+            total += cost;
+        return total;
+    };
+    const availablePoints = () => earned - spentTotal();
+    const grantLevel = (level) => {
+        const amount = sanitizeAmount(evalCurve(perLevel, level));
+        earned += amount;
+        return amount;
+    };
+    return {
+        available: availablePoints,
+        earned: () => earned,
+        spent: spentTotal,
+        grant(amount) {
+            earned += sanitizeAmount(amount);
+        },
+        grantForLevel: grantLevel,
+        grantOnLevelUp(fromLevel, toLevel) {
+            let total = 0;
+            for (let level = fromLevel + 1; level <= toLevel; level += 1)
+                total += grantLevel(level);
+            return total;
+        },
+        canAfford(cost) {
+            return availablePoints() >= cost;
+        },
+        spend(unlockId, cost, opts) {
+            if (!Number.isFinite(cost) || cost < 0)
+                return { ok: false, reason: "invalid-cost" };
+            if (unlocked.has(unlockId))
+                return { ok: false, reason: "already-unlocked" };
+            if (opts?.requires !== undefined && !opts.requires()) {
+                return { ok: false, reason: "missing-prerequisites" };
+            }
+            if (availablePoints() < cost)
+                return { ok: false, reason: "insufficient-points" };
+            unlocked.set(unlockId, cost);
+            return { ok: true, available: availablePoints() };
+        },
+        isUnlocked(id) {
+            return unlocked.has(id);
+        },
+        costOf(id) {
+            return unlocked.get(id) ?? 0;
+        },
+        unlockedIds() {
+            return [...unlocked.keys()];
+        },
+        refund(unlockId) {
+            return unlocked.delete(unlockId);
+        },
+        respec() {
+            const refunded = spentTotal();
+            unlocked.clear();
+            return refunded;
+        },
+        snapshot() {
+            const map = {};
+            for (const [id, cost] of unlocked)
+                map[id] = cost;
+            return { earned, unlocked: map };
+        },
+        hydrate(state) {
+            load(state);
+        },
+    };
+}

package/dist/economy/wallet.d.ts

@@ -8,9 +8,33 @@ export type ChargeResult = {
     status: "rejected";
     reason: "insufficient-funds";
 };
+/**
+ * Opt-in debt affordance for {@link charge}/{@link chargeAll}: `true` allows the balance to go
+ * arbitrarily negative, a number caps how far into the red it may go (the charge is rejected once
+ * `balance - amount` would fall below `-max`). Omitted (the default) keeps the strict no-debt rule.
+ */
+export type Overdraft = boolean | {
+    max: number;
+};
+/** Options for {@link charge}/{@link chargeAll}: opt one call into overdraft debt via `overdraft`. */
+export interface ChargeOptions {
+    overdraft?: Overdraft;
+}
+/**
+ * Hold per-currency balances with affordability checks and charge/grant operations.
+ *
+ * @capability wallet hold currency balances with charge and affordability checks
+ */
 export declare function createEmptyWallet(): WalletState;
 export declare function balance(state: WalletState, currency: string): number;
 export declare function grant(state: WalletState, currency: string, amount: number): WalletState;
-export declare function charge(state: WalletState, currency: string, amount: number): ChargeResult;
+/**
+ * Deduct `amount`, rejecting when it would leave the balance negative unless `options.overdraft`
+ * opts into carrying debt (`true` unlimited, `{ max }` capped) — the strict same-tick affordability
+ * check stays the default with `options` omitted.
+ */
+export declare function charge(state: WalletState, currency: string, amount: number, options?: ChargeOptions): ChargeResult;
+/** True once `balance(state, currency)` has gone negative under an overdraft-enabled charge. */
+export declare function isOverdrawn(state: WalletState, currency: string): boolean;
 export declare function canAfford(state: WalletState, costs: Readonly<Record<string, number>>): boolean;
-export declare function chargeAll(state: WalletState, costs: Readonly<Record<string, number>>): ChargeResult;
+export declare function chargeAll(state: WalletState, costs: Readonly<Record<string, number>>, options?: ChargeOptions): ChargeResult;

package/dist/economy/wallet.js

@@ -1,3 +1,8 @@
+/**
+ * Hold per-currency balances with affordability checks and charge/grant operations.
+ *
+ * @capability wallet hold currency balances with charge and affordability checks
+ */
 export function createEmptyWallet() {
     return { balances: {} };
 }
@@ -18,10 +23,25 @@ export function grant(state, currency, amount) {
         },
     };
 }
-export function charge(state, currency, amount) {
+function withinOverdraft(nextBalance, overdraft) {
+    if (nextBalance >= 0)
+        return true;
+    if (overdraft === undefined || overdraft === false)
+        return false;
+    if (overdraft === true)
+        return true;
+    return nextBalance >= -overdraft.max;
+}
+/**
+ * Deduct `amount`, rejecting when it would leave the balance negative unless `options.overdraft`
+ * opts into carrying debt (`true` unlimited, `{ max }` capped) — the strict same-tick affordability
+ * check stays the default with `options` omitted.
+ */
+export function charge(state, currency, amount, options) {
     assertValidAmount(amount);
     const current = balance(state, currency);
-    if (current < amount) {
+    const next = current - amount;
+    if (!withinOverdraft(next, options?.overdraft)) {
         return { status: "rejected", reason: "insufficient-funds" };
     }
     return {
@@ -29,21 +49,30 @@ export function charge(state, currency, amount) {
         state: {
             balances: {
                 ...state.balances,
-                [currency]: current - amount,
+                [currency]: next,
             },
         },
     };
 }
+/** True once `balance(state, currency)` has gone negative under an overdraft-enabled charge. */
+export function isOverdrawn(state, currency) {
+    return balance(state, currency) < 0;
+}
 export function canAfford(state, costs) {
     return Object.entries(costs).every(([currency, amount]) => balance(state, currency) >= amount);
 }
-export function chargeAll(state, costs) {
-    if (!canAfford(state, costs)) {
+export function chargeAll(state, costs, options) {
+    const overdraft = options?.overdraft;
+    if (overdraft === undefined && !canAfford(state, costs)) {
         return { status: "rejected", reason: "insufficient-funds" };
     }
     const balances = { ...state.balances };
     for (const [currency, amount] of Object.entries(costs)) {
-        balances[currency] = balance(state, currency) - amount;
+        const next = balance(state, currency) - amount;
+        if (!withinOverdraft(next, overdraft)) {
+            return { status: "rejected", reason: "insufficient-funds" };
+        }
+        balances[currency] = next;
     }
     return { status: "ok", state: { balances } };
 }

package/dist/editor/commandApply.d.ts

@@ -0,0 +1,5 @@
+import type { EditorCommand, EditorSessionState } from "./commands.js";
+/** Apply a mutating editor command; returns null when the command type has no handler. @internal */
+export declare function applyMutating(state: EditorSessionState, command: EditorCommand): EditorSessionState | null;
+/** True when the command changes document structure (not select/undo/redo). @internal */
+export declare function isStructural(command: EditorCommand): boolean;