@jgengine/core 0.10.0 → 0.12.0

package/dist/devtools/tunableSchema.js

@@ -6,12 +6,15 @@ export const MAX_SCAN_TARGETS = 512;
 const COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
 const UNSAFE_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 const DEFAULT_AXIS = ["x", "y", "z", "w"];
+/** @internal */
 export function isFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
+/** @internal */
 export function escapePathSegment(segment) {
     return segment.replace(/\\/g, "\\\\").replace(/\./g, "\\.");
 }
+/** @internal */
 export function unescapePathSegment(segment) {
     let out = "";
     for (let i = 0; i < segment.length; i += 1) {
@@ -25,10 +28,12 @@ export function unescapePathSegment(segment) {
     }
     return out;
 }
+/** @internal */
 export function joinTunablePath(parent, segment) {
     const escaped = escapePathSegment(segment);
     return parent === "" ? escaped : `${parent}.${escaped}`;
 }
+/** @internal */
 export function splitTunablePath(path) {
     const parts = [];
     let current = "";
@@ -49,6 +54,7 @@ export function splitTunablePath(path) {
     parts.push(unescapePathSegment(current));
     return parts;
 }
+/** @internal */
 export function parseColor(input) {
     if (typeof input !== "string" || !COLOR_PATTERN.test(input))
         return null;
@@ -81,6 +87,7 @@ export function parseColor(input) {
     const hex = `${rgb}${a.toLowerCase()}`;
     return { hex, rgb, alpha, hasAlpha: true };
 }
+/** @internal */
 export function formatColor(rgb, alpha, withAlpha) {
     const parsed = parseColor(rgb);
     const rgbHex = parsed?.rgb ?? (/^#[0-9a-fA-F]{6}$/.test(rgb) ? rgb.toLowerCase() : null);
@@ -94,6 +101,7 @@ export function formatColor(rgb, alpha, withAlpha) {
         .padStart(2, "0");
     return `${rgbHex}${a}`;
 }
+/** @internal */
 export function normalizeColorValue(input, forceAlpha) {
     const parsed = parseColor(input);
     if (parsed === null)
@@ -103,9 +111,11 @@ export function normalizeColorValue(input, forceAlpha) {
     }
     return parsed.rgb;
 }
+/** @internal */
 export function isColorString(value) {
     return typeof value === "string" && COLOR_PATTERN.test(value);
 }
+/** @internal */
 export function vecLength(kind) {
     if (kind === "vec2")
         return 2;
@@ -113,11 +123,13 @@ export function vecLength(kind) {
         return 3;
     return 4;
 }
+/** @internal */
 export function isNumericTuple(value, length) {
     if (!Array.isArray(value) || value.length !== length)
         return false;
     return value.every(isFiniteNumber);
 }
+/** @internal */
 export function isIntervalShape(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
         return false;
@@ -127,6 +139,7 @@ export function isIntervalShape(value) {
         return false;
     return isFiniteNumber(record.min) && isFiniteNumber(record.max);
 }
+/** @internal */
 export function expandAxisMeta(length, labels, min, max, step, sample) {
     const resolvedLabels = Array.from({ length }, (_, i) => labels?.[i] ?? DEFAULT_AXIS[i] ?? `a${i}`);
     const resolvedMin = Array.from({ length }, (_, i) => {
@@ -154,15 +167,18 @@ export function expandAxisMeta(length, labels, min, max, step, sample) {
     });
     return { labels: resolvedLabels, min: resolvedMin, max: resolvedMax, step: resolvedStep };
 }
+/** @internal */
 export function clampAxisValue(value, min, max) {
     return Math.min(max, Math.max(min, value));
 }
+/** @internal */
 export function parseVec(kind, raw, bounds) {
     const length = vecLength(kind);
     if (!isNumericTuple(raw, length))
         return null;
     return raw.map((value, i) => clampAxisValue(value, bounds.min[i], bounds.max[i]));
 }
+/** @internal */
 export function parseInterval(raw, options) {
     if (!isIntervalShape(raw))
         return null;
@@ -200,6 +216,7 @@ export function parseInterval(raw, options) {
     }
     return { min: lo, max: hi };
 }
+/** @internal */
 export function convertAngle(value, from, to) {
     if (from === to)
         return value;
@@ -207,6 +224,7 @@ export function convertAngle(value, from, to) {
         return (value * Math.PI) / 180;
     return (value * 180) / Math.PI;
 }
+/** @internal */
 export function normalizeAngle(value, unit, options) {
     let next = value;
     if (options.wrap === true) {
@@ -225,6 +243,7 @@ export function normalizeAngle(value, unit, options) {
     }
     return next;
 }
+/** @internal */
 export function resolveChoices(options, choices) {
     if (choices !== undefined)
         return choices;
@@ -232,22 +251,26 @@ export function resolveChoices(options, choices) {
         return options.map((value) => ({ value }));
     return undefined;
 }
+/** @internal */
 export function choiceValues(choices) {
     if (choices === undefined)
         return undefined;
     return choices.map((choice) => choice.value);
 }
+/** @internal */
 export function findChoice(choices, raw) {
     if (choices === undefined)
         return undefined;
     return choices.find((choice) => Object.is(choice.value, raw));
 }
+/** @internal */
 export function parseEnumValue(raw, choices) {
     if (choices === undefined)
         return null;
     const match = findChoice(choices, raw);
     return match === undefined ? null : match.value;
 }
+/** @internal */
 export function coerceSelectWrite(raw, choices, options) {
     if (choices !== undefined) {
         const byValue = findChoice(choices, raw);
@@ -275,6 +298,7 @@ export function coerceSelectWrite(raw, choices, options) {
     }
     return raw;
 }
+/** @internal */
 export function inferKind(initial, options) {
     if (options?.kind !== undefined)
         return options.kind;
@@ -289,6 +313,7 @@ export function inferKind(initial, options) {
         return "color";
     return "text";
 }
+/** @internal */
 export function discoverableKind(value, meta) {
     if (meta?.kind !== undefined) {
         if (meta.kind === "vec2" || meta.kind === "vec3" || meta.kind === "vec4") {
@@ -320,6 +345,7 @@ export function discoverableKind(value, meta) {
         return "color";
     return null;
 }
+/** @internal */
 export function isScannableContainer(value) {
     if (value === null || typeof value !== "object")
         return false;
@@ -328,6 +354,7 @@ export function isScannableContainer(value) {
     const proto = Object.getPrototypeOf(value);
     return proto === Object.prototype || proto === null;
 }
+/** @internal */
 export function ownWritableDataKeys(target) {
     return Object.keys(target).filter((key) => {
         if (UNSAFE_KEYS.has(key))
@@ -342,12 +369,14 @@ export function ownWritableDataKeys(target) {
         return true;
     });
 }
+/** @internal */
 export function sliderBounds(initial, options) {
     const min = options?.min ?? (initial < 0 ? initial * 2 : 0);
     const max = options?.max ?? (initial > 0 ? initial * 2 : initial < 0 ? 0 : 1);
     const step = options?.step ?? (max - min) / 100;
     return { min, max, step };
 }
+/** @internal */
 export function validateControlValue(kind, raw, context) {
     switch (kind) {
         case "slider": {
@@ -420,6 +449,7 @@ export function validateControlValue(kind, raw, context) {
             return { ok: false, reason: "unknown kind" };
     }
 }
+/** @internal */
 export function parseOverridesPayload(raw) {
     if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
         return { overrides: null, diagnostics: ["overrides payload is not an object"] };
@@ -467,6 +497,7 @@ export function parseOverridesPayload(raw) {
         diagnostics: version === 0 ? ["migrated unversioned overrides to v1"] : [],
     };
 }
+/** @internal */
 export function cloneValue(value) {
     if (Array.isArray(value))
         return value.slice();

package/dist/devtools/types.d.ts

@@ -0,0 +1,212 @@
+import type { ChangeSignal } from "../store/changeSignal.js";
+import type { AngleUnit, DevtoolsControlKind, DevtoolsOverrides, DiscoverySkip, OverrideApplyDiagnostic, ScanMeta, TunableChoice, TunableOptions } from "./tunableSchema.js";
+/** Registered tunable control with its resolved schema metadata and read/write/reset accessors. */
+export interface DevtoolsControl {
+    readonly name: string;
+    readonly kind: DevtoolsControlKind;
+    readonly label: string;
+    readonly group: string;
+    readonly initial: unknown;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly options?: readonly unknown[];
+    readonly choices?: readonly TunableChoice[];
+    readonly unit?: AngleUnit;
+    readonly displayUnit?: AngleUnit;
+    readonly wrap?: boolean;
+    readonly integer?: boolean;
+    readonly axisLabels?: readonly string[];
+    readonly axisMin?: readonly number[];
+    readonly axisMax?: readonly number[];
+    readonly axisStep?: readonly number[];
+    readonly hasAlpha?: boolean;
+    readonly schemaVersion: number;
+    read(): unknown;
+    write(value: unknown): boolean;
+    reset(): void;
+}
+/** Typed handle to a registered control, exposing its live value and subscribe/set/reset operations. */
+export interface Tunable<T> {
+    readonly name: string;
+    readonly kind: DevtoolsControlKind;
+    readonly initial: T;
+    readonly value: T;
+    set(value: T): boolean;
+    reset(): void;
+    subscribe(listener: (value: T) => void): () => void;
+}
+/** Outcome of applying a devtools overrides payload: counts of applied and skipped entries plus diagnostics. */
+export interface OverrideApplyResult {
+    applied: number;
+    skipped: readonly OverrideApplyDiagnostic[];
+    diagnostics: readonly string[];
+}
+/** Aggregated frame-timing statistics over the recent sampling window, including per-phase breakdown. */
+export interface FrameStats {
+    fps: number;
+    avgFrameMs: number;
+    p95FrameMs: number;
+    maxFrameMs: number;
+    avgSimMs: number;
+    maxSimMs: number;
+    avgOutsideMs: number;
+    maxOutsideMs: number;
+    longFrames: number;
+    samples: number;
+    recentFrameMs: readonly number[];
+    phases: readonly PhaseStats[];
+}
+/** Timing summary for a single named profiling phase across the sampling window. */
+export interface PhaseStats {
+    name: string;
+    avgMs: number;
+    maxMs: number;
+    lastMs: number;
+    samples: number;
+    pctOfSim: number;
+}
+/** Recorded spike event for a frame that exceeded the long-frame threshold, with culprit attribution. */
+export interface LongFrameEvent {
+    at: number;
+    frameMs: number;
+    simMs: number;
+    outsideMs: number;
+    phases: readonly {
+        name: string;
+        ms: number;
+        pct: number;
+    }[];
+    topPhase: string | null;
+    culprit: string;
+    reason: string;
+    probes: Record<string, unknown>;
+    render: RenderSample | null;
+}
+/** Snapshot of renderer resource counts (draw calls, triangles, geometries, textures) for a frame. */
+export interface RenderSample {
+    drawCalls: number;
+    triangles: number;
+    geometries: number;
+    textures: number;
+}
+/** Aggregated latency statistics (last/avg/min/max) over recorded latency samples. */
+export interface LatencyStats {
+    lastMs: number;
+    avgMs: number;
+    minMs: number;
+    maxMs: number;
+    samples: number;
+}
+/** Severity level for a captured devtools log entry. */
+export type DevtoolsLogLevel = "log" | "info" | "warn" | "error";
+/** A single captured log line with timestamp, level, and formatted message. */
+export interface DevtoolsLogEntry {
+    at: number;
+    level: DevtoolsLogLevel;
+    message: string;
+}
+/** A control auto-discovered by scanning an object/table, with its binding metadata and current reader. */
+export interface DiscoveredEntry {
+    readonly id: string;
+    readonly table: string;
+    readonly key: string;
+    readonly kind: DevtoolsControlKind;
+    readonly initial: unknown;
+    readonly enabled: boolean;
+    read(): unknown;
+}
+/** Get/set accessor pair plus initial value used to bind a discovered field to a control. */
+export interface TunableAccessor {
+    initial: unknown;
+    get(): unknown;
+    set(value: unknown): void;
+}
+/** Serializable point-in-time snapshot of devtools state: frame, render, latency, logs, controls, and discovered fields. */
+export interface DevtoolsSnapshot {
+    at: number;
+    frame: FrameStats | null;
+    render: RenderSample | null;
+    latency: LatencyStats | null;
+    longFrames: readonly LongFrameEvent[];
+    logs: readonly DevtoolsLogEntry[];
+    probes: Record<string, unknown>;
+    controls: readonly {
+        name: string;
+        kind: DevtoolsControlKind;
+        value: unknown;
+        initial: unknown;
+    }[];
+    discovered: readonly {
+        id: string;
+        kind: DevtoolsControlKind;
+        value: unknown;
+        enabled: boolean;
+    }[];
+    skipped: readonly DiscoverySkip[];
+}
+/** Per-frame timing input recorded by callers: total frame time, sim time, and optional named phase durations. */
+export interface FrameRecordSample {
+    frameMs: number;
+    simMs: number;
+    phases?: Readonly<Record<string, number>>;
+}
+/** Top-level devtools facade aggregating frame, profile, render, logs, latency, controls, discover, overrides, and probes. */
+export interface Devtools {
+    frame: {
+        record(sample: FrameRecordSample): void;
+        stats(): FrameStats | null;
+        longFrames(): readonly LongFrameEvent[];
+        clearLongFrames(): void;
+        /** Drop all frame/phase/long-frame history so the next stats() window starts clean — use after load/shader warmup before measuring. */
+        reset(): void;
+    };
+    profile: {
+        begin(name: string): () => void;
+        measure<T>(name: string, fn: () => T): T;
+        add(name: string, ms: number): void;
+        current(): Record<string, number>;
+        reset(): void;
+    };
+    render: {
+        record(sample: RenderSample): void;
+        latest(): RenderSample | null;
+    };
+    logs: {
+        push(level: DevtoolsLogLevel, message: string): void;
+        captureConsole(): void;
+        list(): readonly DevtoolsLogEntry[];
+        clear(): void;
+    };
+    latency: {
+        record(ms: number): void;
+        stats(): LatencyStats | null;
+    };
+    controls: {
+        register<T>(name: string, initial: T, options?: TunableOptions<T>): Tunable<T>;
+        list(): readonly DevtoolsControl[];
+        get(name: string): DevtoolsControl | null;
+        remove(name: string): void;
+        resetAll(): void;
+    };
+    discover: {
+        bind(table: string, key: string, accessor: TunableAccessor, options?: TunableOptions): void;
+        scanTable(table: string, candidate: unknown, meta?: ScanMeta): number;
+        scanModule(exports: Record<string, unknown>, meta?: ScanMeta): number;
+        list(): readonly DiscoveredEntry[];
+        skipped(): readonly DiscoverySkip[];
+        enable(id: string): void;
+        disable(id: string): void;
+        clear(): void;
+    };
+    overrides: {
+        export(): DevtoolsOverrides;
+        apply(overrides: DevtoolsOverrides | unknown): OverrideApplyResult;
+    };
+    probes: {
+        register(name: string, read: () => unknown): () => void;
+        read(): Record<string, unknown>;
+    };
+    signal: ChangeSignal;
+    snapshot(): DevtoolsSnapshot;
+}

package/dist/devtools/types.js

@@ -0,0 +1 @@
+export {};

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;