@jgengine/core 0.9.0 → 0.11.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/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/commands.d.ts

@@ -0,0 +1,248 @@
+import { type SurfaceDelta, type TerraformDelta, type TerrainMaterialLayer, type WeightDelta } from "../world/terraform.js";
+import { type EditorUiDocument, type EditorUiPanelLayout } from "../ui/hudDocument.js";
+import { type EditorGridCellEdit, type EditorGridLayer } from "./grid.js";
+import type { EditorDocument, EditorMarker, EditorNote, EditorPath, EditorTerrain, EditorVec3, EditorVolume } from "./types.js";
+/** A single editor mutation — select, move, add, remove, undo/redo — dispatched to a session. */
+export type EditorCommand = {
+    type: "select";
+    ids: readonly string[];
+} | {
+    type: "clearSelection";
+} | {
+    type: "setTransform";
+    id: string;
+    position?: EditorVec3;
+    rotationY?: number;
+} | {
+    type: "translate";
+    ids: readonly string[];
+    delta: EditorVec3;
+} | {
+    type: "setParent";
+    ids: readonly string[];
+    parentId: string | null;
+} | {
+    type: "addMarker";
+    marker: EditorMarker;
+} | {
+    type: "addVolume";
+    volume: EditorVolume;
+} | {
+    type: "addPath";
+    path: EditorPath;
+} | {
+    type: "addNote";
+    note: EditorNote;
+} | {
+    type: "setMarker";
+    id: string;
+    patch: Partial<Omit<EditorMarker, "id">>;
+} | {
+    type: "setVolume";
+    id: string;
+    patch: Partial<Omit<EditorVolume, "id">>;
+} | {
+    type: "setPath";
+    id: string;
+    patch: Partial<Omit<EditorPath, "id">>;
+} | {
+    type: "setNote";
+    id: string;
+    patch: Partial<Omit<EditorNote, "id">>;
+} | {
+    type: "setCatalogEntry";
+    catalogId: string;
+    entryId: string;
+    patch: {
+        label?: string;
+        meta?: Record<string, unknown>;
+    };
+} | {
+    type: "remove";
+    id: string;
+} | {
+    type: "removeMany";
+    ids: readonly string[];
+} | {
+    type: "duplicate";
+    ids: readonly string[];
+    offset?: EditorVec3;
+} | {
+    type: "addFragment";
+    fragment: EditorDocument;
+    offset?: EditorVec3;
+} | {
+    type: "importDocument";
+    document: EditorDocument;
+} | {
+    type: "importJson";
+    json: string;
+} | {
+    type: "replaceDocument";
+    document: EditorDocument;
+} | {
+    type: "setTerrain";
+    terrain: EditorTerrain;
+} | {
+    type: "sculptTerrain";
+    delta: TerraformDelta;
+} | {
+    type: "paintTerrain";
+    delta: SurfaceDelta;
+} | {
+    type: "setTerrainLayers";
+    layers: readonly TerrainMaterialLayer[];
+} | {
+    type: "blendTerrain";
+    delta: WeightDelta;
+} | {
+    type: "clearTerrain";
+} | {
+    type: "convertScatterToObjects";
+    pathId: string;
+    markers: readonly EditorMarker[];
+} | {
+    type: "createPrefab";
+    id: string;
+    name: string;
+    ids: readonly string[];
+} | {
+    type: "insertPrefab";
+    prefabId: string;
+    at: EditorVec3;
+    instanceId?: string;
+} | {
+    type: "detachPrefabInstance";
+    instanceId: string;
+} | {
+    type: "deletePrefab";
+    prefabId: string;
+} | {
+    type: "createCollection";
+    id: string;
+    name: string;
+    memberIds?: readonly string[];
+} | {
+    type: "renameCollection";
+    id: string;
+    name: string;
+} | {
+    type: "deleteCollection";
+    id: string;
+} | {
+    type: "setCollectionMembers";
+    id: string;
+    memberIds: readonly string[];
+} | {
+    type: "addToCollection";
+    id: string;
+    ids: readonly string[];
+} | {
+    type: "removeFromCollection";
+    id: string;
+    ids: readonly string[];
+} | {
+    type: "setCollectionFlags";
+    id: string;
+    patch: {
+        color?: string;
+        locked?: boolean;
+        visible?: boolean;
+    };
+} | {
+    type: "selectCollection";
+    id: string;
+} | {
+    type: "batchSetProperties";
+    ids: readonly string[];
+    patch: {
+        color?: string;
+        label?: string;
+        meta?: Record<string, unknown>;
+    };
+} | {
+    type: "assignMaterial";
+    ids: readonly string[];
+    materialId: string;
+} | {
+    type: "addGridLayer";
+    layer: EditorGridLayer;
+} | {
+    type: "removeGridLayer";
+    id: string;
+} | {
+    type: "setGridLayer";
+    id: string;
+    patch: Partial<Omit<EditorGridLayer, "id" | "cells">>;
+} | {
+    type: "paintGridCells";
+    id: string;
+    cells: readonly EditorGridCellEdit[];
+} | {
+    type: "fillGridRect";
+    id: string;
+    col0: number;
+    row0: number;
+    col1: number;
+    row1: number;
+    value: string;
+} | {
+    type: "floodFillGrid";
+    id: string;
+    col: number;
+    row: number;
+    value: string;
+} | {
+    type: "resizeGridLayer";
+    id: string;
+    cols: number;
+    rows: number;
+} | {
+    type: "setUiPanel";
+    id: string;
+    patch: Partial<EditorUiPanelLayout>;
+} | {
+    type: "removeUiPanel";
+    id: string;
+} | {
+    type: "setUi";
+    ui: EditorUiDocument | undefined;
+} | {
+    type: "undo";
+} | {
+    type: "redo";
+};
+/** Per-dispatch options; `coalesce` merges consecutive same-key edits into one undo step. */
+export interface EditorDispatchOptions {
+    coalesce?: string;
+}
+/** The document plus current selection at a point in editor history. */
+export interface EditorSessionState {
+    document: EditorDocument;
+    selection: string[];
+}
+/** Stateful, undoable handle for driving scene edits from UI or an MCP agent. */
+export interface EditorSession {
+    getState(): EditorSessionState;
+    subscribe(listener: (state: EditorSessionState) => void): () => void;
+    dispatch(command: EditorCommand, options?: EditorDispatchOptions): EditorSessionState;
+    exportJson(pretty?: boolean): string;
+    canUndo(): boolean;
+    canRedo(): boolean;
+}
+/** Creates an editor session with undo/redo history seeded from an initial document.
+ * @internal
+ */
+export declare function createEditorSession(initial: EditorDocument, historyLimit?: number): EditorSession;
+/** Compact snapshot of a session state — counts, selection, and the selected object.
+ * @internal
+ */
+export declare function summarizeEditorSession(state: EditorSessionState): {
+    markers: number;
+    volumes: number;
+    paths: number;
+    annotations: number;
+    selection: string[];
+    selectedMarker?: EditorMarker;
+    selectedVolume?: EditorVolume;
+};