@jgengine/core 0.9.0 → 0.11.0

package/dist/combat/statusApplication.js

@@ -0,0 +1,81 @@
+function clamp01(value) {
+    if (value < 0)
+        return 0;
+    if (value > 1)
+        return 1;
+    return value;
+}
+/**
+ * Resolve one status application: reject on immunity, roll landing chance against injected RNG,
+ * scale magnitude/duration by the matchup, then fold into any existing instance per the stacking
+ * policy. Deterministic given a seeded `rng`; pure over serializable data, so authority can run it
+ * and replicate only the returned `instance`.
+ *
+ * @capability status-application resolve a data-defined status application with chance, matchup scaling, and stacking policy
+ */
+export function resolveStatusApplication(input) {
+    const { spec, scale, current, immunity, source } = input;
+    const rng = input.rng ?? Math.random;
+    if (immunity?.statuses?.includes(spec.status) === true) {
+        return { kind: "immune", instance: current ?? null, chance: 0, roll: null };
+    }
+    const present = current ?? null;
+    const policy = spec.stack ?? { kind: "refresh" };
+    if (present !== null && policy.kind === "ignore") {
+        return { kind: "ignored", instance: present, chance: 0, roll: null };
+    }
+    const chance = clamp01((spec.chance ?? 1) * (scale?.applyChance ?? 1));
+    const roll = rng();
+    if (roll >= chance) {
+        return { kind: "missed", instance: present, chance, roll };
+    }
+    const magnitude = (spec.magnitude ?? 0) * (scale?.magnitude ?? 1);
+    const durationMs = (spec.durationMs ?? 0) * (scale?.duration ?? 1);
+    const ticks = Math.round((spec.ticks ?? 0) * (scale?.duration ?? 1));
+    if (present === null) {
+        const instance = {
+            status: spec.status,
+            stacks: 1,
+            remainingMs: durationMs,
+            ticks,
+            magnitude,
+            ...(source !== undefined ? { source } : {}),
+        };
+        return { kind: "applied", instance, chance, roll };
+    }
+    if (policy.kind === "replace") {
+        const instance = {
+            status: spec.status,
+            stacks: 1,
+            remainingMs: durationMs,
+            ticks,
+            magnitude,
+            ...(source !== undefined ? { source } : {}),
+        };
+        return { kind: "replaced", instance, chance, roll };
+    }
+    if (policy.kind === "stack") {
+        const add = policy.add ?? 1;
+        const max = policy.max ?? Number.POSITIVE_INFINITY;
+        const stacks = Math.min(max, present.stacks + add);
+        const instance = {
+            status: spec.status,
+            stacks,
+            remainingMs: durationMs,
+            ticks,
+            magnitude,
+            ...(source !== undefined ? { source } : present.source !== undefined ? { source: present.source } : {}),
+        };
+        return { kind: "stacked", instance, chance, roll };
+    }
+    // refresh: reset duration/ticks/magnitude, keep stack count.
+    const instance = {
+        status: spec.status,
+        stacks: present.stacks,
+        remainingMs: durationMs,
+        ticks,
+        magnitude,
+        ...(source !== undefined ? { source } : present.source !== undefined ? { source: present.source } : {}),
+    };
+    return { kind: "refreshed", instance, chance, roll };
+}

package/dist/combat/telegraph.d.ts

@@ -23,6 +23,7 @@ export interface TelegraphConfig {
     turns?: number;
     kind?: string;
 }
+/** @internal */
 export declare function telegraphProgress(windupMs: number, startedAtMs: number, nowMs: number): number;
 export interface HazardCycleConfig {
     windupMs: number;
@@ -45,12 +46,20 @@ export interface HazardCycleSample {
  * Deterministic repeating hazard timing — windup → active → cooldown as a pure function of absolute
  * time, for recurring flame vents, crushers, lightning rings. Sample `hazardCycleAt` each tick: draw
  * the telegraph during `windup`, apply the effect during `active`, rest through `cooldown`.
- */
+  * @internal
+  */
 export declare function hazardCycleAt(config: HazardCycleConfig, nowMs: number): HazardCycleSample;
-/** Absolute time the hazard's next `active` phase begins at or after `nowMs` — the countdown seam. */
+/** Absolute time the hazard's next `active` phase begins at or after `nowMs` — the countdown seam.
+ * @internal
+ */
 export declare function nextHazardActiveAt(config: HazardCycleConfig, nowMs: number): number;
+/** @internal */
 export declare function telegraphFired(windupMs: number, startedAtMs: number, nowMs: number): boolean;
+/** @internal */
 export declare function telegraphTurnProgress(config: TelegraphConfig, startedTurn: number, currentTurn: number): number;
+/** @internal */
 export declare function telegraphFiredAtTurn(config: TelegraphConfig, startedTurn: number, currentTurn: number): boolean;
+/** @internal */
 export declare function telegraphTurnsRemaining(config: TelegraphConfig, startedTurn: number, currentTurn: number): number;
+/** @internal */
 export declare function pointInTelegraph(config: TelegraphConfig, point: EntityPosition): boolean;

package/dist/combat/telegraph.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function telegraphProgress(windupMs, startedAtMs, nowMs) {
     if (windupMs <= 0)
         return 1;
@@ -7,7 +8,8 @@ export function telegraphProgress(windupMs, startedAtMs, nowMs) {
  * Deterministic repeating hazard timing — windup → active → cooldown as a pure function of absolute
  * time, for recurring flame vents, crushers, lightning rings. Sample `hazardCycleAt` each tick: draw
  * the telegraph during `windup`, apply the effect during `active`, rest through `cooldown`.
- */
+  * @internal
+  */
 export function hazardCycleAt(config, nowMs) {
     const cooldownMs = Math.max(0, config.cooldownMs ?? 0);
     const cycleMs = config.windupMs + config.activeMs + cooldownMs;
@@ -41,7 +43,9 @@ export function hazardCycleAt(config, nowMs) {
         cycleIndex,
     };
 }
-/** Absolute time the hazard's next `active` phase begins at or after `nowMs` — the countdown seam. */
+/** Absolute time the hazard's next `active` phase begins at or after `nowMs` — the countdown seam.
+ * @internal
+ */
 export function nextHazardActiveAt(config, nowMs) {
     const sample = hazardCycleAt(config, nowMs);
     if (sample.phase === "windup")
@@ -50,19 +54,23 @@ export function nextHazardActiveAt(config, nowMs) {
     const restMs = sample.phase === "active" ? sample.remainingMs + cooldownMs : sample.remainingMs;
     return nowMs + restMs + config.windupMs;
 }
+/** @internal */
 export function telegraphFired(windupMs, startedAtMs, nowMs) {
     return nowMs - startedAtMs >= windupMs;
 }
+/** @internal */
 export function telegraphTurnProgress(config, startedTurn, currentTurn) {
     const turns = config.turns ?? 0;
     if (turns <= 0)
         return 1;
     return Math.max(0, Math.min(1, (currentTurn - startedTurn) / turns));
 }
+/** @internal */
 export function telegraphFiredAtTurn(config, startedTurn, currentTurn) {
     const turns = config.turns ?? 0;
     return currentTurn - startedTurn >= turns;
 }
+/** @internal */
 export function telegraphTurnsRemaining(config, startedTurn, currentTurn) {
     const turns = config.turns ?? 0;
     return Math.max(0, turns - (currentTurn - startedTurn));
@@ -70,6 +78,7 @@ export function telegraphTurnsRemaining(config, startedTurn, currentTurn) {
 function planarDelta(config, point) {
     return { dx: point[0] - config.at[0], dz: point[2] - config.at[2] };
 }
+/** @internal */
 export function pointInTelegraph(config, point) {
     const { shape } = config;
     const { dx, dz } = planarDelta(config, point);

package/dist/combat/thresholdCrossings.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Generic numeric threshold-crossing tracker (#931).
+ *
+ * A reusable state helper that watches a single numeric source (boss HP percent,
+ * a resource pool, an armor gauge, an objective counter) and emits ordered
+ * crossing events as named thresholds are passed. Supports crossing direction,
+ * a hysteresis band to prevent chatter, a once/repeat policy, and skipped
+ * threshold handling (a single large jump emits every threshold it passed, in
+ * order). Deterministic and fully serializable so save/load round-trips cleanly.
+ *
+ * This is intentionally NOT boss-specific: health-gating, phase transitions,
+ * armor breaks, music stingers, and resource warnings are all the same
+ * primitive. Consumers wire emitted crossings to whatever effect they own —
+ * e.g. installing an immunity interceptor from `combat/damageInterceptors`.
+ */
+/** A named threshold on the numeric source. */
+export interface ThresholdMark {
+    /** Stable identifier emitted on crossing and used in the fired-once ledger. */
+    id: string;
+    /** The value at which this threshold sits. */
+    at: number;
+}
+/** The direction a crossing moved: `falling` = value decreased past the mark, `rising` = increased past it. */
+export type CrossingDirection = "falling" | "rising";
+/** Which directions should emit crossings. */
+export type CrossingTrigger = "falling" | "rising" | "both";
+/** Whether a threshold may fire repeatedly (`repeat`) or at most once per direction (`once`). */
+export type CrossingPolicy = "once" | "repeat";
+/** Caller configuration for a threshold tracker. */
+export interface ThresholdCrossingConfig {
+    /** Thresholds to watch; order is irrelevant, the tracker sorts by `at`. */
+    thresholds: readonly ThresholdMark[];
+    /** Directions that emit crossings; defaults to `"both"`. */
+    trigger?: CrossingTrigger;
+    /** Symmetric dead-band around each mark that a value must fully clear to flip sides; defaults to `0`. */
+    hysteresis?: number;
+    /** `repeat` (default) re-fires on every crossing; `once` fires each threshold at most once per direction. */
+    policy?: CrossingPolicy;
+    /** Seed value. When provided, initial sides are computed from it and no crossing is emitted for the seed. */
+    initial?: number;
+}
+/** One emitted crossing: which threshold, which way, and the value span that produced it. */
+export interface ThresholdCrossing {
+    /** The crossed threshold's id. */
+    id: string;
+    /** The crossed threshold's value. */
+    at: number;
+    /** Direction of the crossing. */
+    direction: CrossingDirection;
+    /** Value before this update. */
+    from: number;
+    /** Value after this update. */
+    to: number;
+}
+/** Serializable tracker state for save/load. */
+export interface ThresholdTrackerSnapshot {
+    /** Last observed value, or `null` before the first observation. */
+    last: number | null;
+    /** Committed side (`"above"`/`"below"`) per threshold id. */
+    sides: Record<string, "above" | "below">;
+    /** Fired ledger entries (`"<id>:<direction>"`) for the `once` policy. */
+    fired: string[];
+}
+/** A stateful crossing tracker over one numeric source. */
+export interface ThresholdTracker {
+    /** Observe a new value and return the crossings it produced, in travel order. */
+    update(value: number): ThresholdCrossing[];
+    /** The last observed value, or `null` before the first `update`/seed. */
+    value(): number | null;
+    /** Clear the fired ledger; reseed sides from `initial` if given, else await the next `update`. */
+    reset(initial?: number): void;
+    /** Serializable snapshot. */
+    snapshot(): ThresholdTrackerSnapshot;
+    /** Restore from a snapshot. */
+    restore(snap: ThresholdTrackerSnapshot): void;
+}
+/**
+ * Track a numeric source against named thresholds and emit ordered crossing
+ * events with direction, hysteresis, once/repeat policy, and skipped-threshold
+ * handling. Deterministic and serializable; drives phase transitions, armor
+ * breaks, resource warnings, and any other threshold consumer.
+ *
+ * @capability threshold-crossings emit ordered crossing events as a numeric source passes named thresholds with hysteresis and once/repeat policy
+ */
+export declare function createThresholdTracker(config: ThresholdCrossingConfig): ThresholdTracker;

package/dist/combat/thresholdCrossings.js

@@ -0,0 +1,116 @@
+/**
+ * Generic numeric threshold-crossing tracker (#931).
+ *
+ * A reusable state helper that watches a single numeric source (boss HP percent,
+ * a resource pool, an armor gauge, an objective counter) and emits ordered
+ * crossing events as named thresholds are passed. Supports crossing direction,
+ * a hysteresis band to prevent chatter, a once/repeat policy, and skipped
+ * threshold handling (a single large jump emits every threshold it passed, in
+ * order). Deterministic and fully serializable so save/load round-trips cleanly.
+ *
+ * This is intentionally NOT boss-specific: health-gating, phase transitions,
+ * armor breaks, music stingers, and resource warnings are all the same
+ * primitive. Consumers wire emitted crossings to whatever effect they own —
+ * e.g. installing an immunity interceptor from `combat/damageInterceptors`.
+ */
+/**
+ * Track a numeric source against named thresholds and emit ordered crossing
+ * events with direction, hysteresis, once/repeat policy, and skipped-threshold
+ * handling. Deterministic and serializable; drives phase transitions, armor
+ * breaks, resource warnings, and any other threshold consumer.
+ *
+ * @capability threshold-crossings emit ordered crossing events as a numeric source passes named thresholds with hysteresis and once/repeat policy
+ */
+export function createThresholdTracker(config) {
+    const trigger = config.trigger ?? "both";
+    const hysteresis = Math.max(0, config.hysteresis ?? 0);
+    const policy = config.policy ?? "repeat";
+    const marks = [...config.thresholds].sort((a, b) => a.at - b.at);
+    const sides = new Map();
+    const fired = new Set();
+    let last = null;
+    function sideOf(value, at) {
+        return value >= at ? "above" : "below";
+    }
+    function seed(value) {
+        sides.clear();
+        for (const mark of marks)
+            sides.set(mark.id, sideOf(value, mark.at));
+    }
+    function allows(direction) {
+        return trigger === "both" || trigger === direction;
+    }
+    if (config.initial !== undefined) {
+        seed(config.initial);
+        last = config.initial;
+    }
+    return {
+        update(value) {
+            if (last === null) {
+                seed(value);
+                last = value;
+                return [];
+            }
+            const from = last;
+            const crossings = [];
+            for (const mark of marks) {
+                const side = sides.get(mark.id);
+                if (side === undefined) {
+                    sides.set(mark.id, sideOf(value, mark.at));
+                    continue;
+                }
+                let next = null;
+                let direction = null;
+                if (side === "above" && value < mark.at - hysteresis) {
+                    next = "below";
+                    direction = "falling";
+                }
+                else if (side === "below" && value > mark.at + hysteresis) {
+                    next = "above";
+                    direction = "rising";
+                }
+                if (next === null || direction === null)
+                    continue;
+                sides.set(mark.id, next);
+                if (!allows(direction))
+                    continue;
+                const key = `${mark.id}:${direction}`;
+                if (policy === "once" && fired.has(key))
+                    continue;
+                fired.add(key);
+                crossings.push({ id: mark.id, at: mark.at, direction, from, to: value });
+            }
+            last = value;
+            // Emit in travel order: falling crosses higher marks first, rising crosses lower marks first.
+            const falling = value < from;
+            crossings.sort((a, b) => (falling ? b.at - a.at : a.at - b.at));
+            return crossings;
+        },
+        value() {
+            return last;
+        },
+        reset(initial) {
+            fired.clear();
+            if (initial === undefined) {
+                sides.clear();
+                last = null;
+            }
+            else {
+                seed(initial);
+                last = initial;
+            }
+        },
+        snapshot() {
+            return { last, sides: Object.fromEntries(sides), fired: [...fired] };
+        },
+        restore(snap) {
+            last = snap.last;
+            sides.clear();
+            for (const [id, side] of Object.entries(snap.sides))
+                sides.set(id, side);
+            fired.clear();
+            for (const key of snap.fired)
+                fired.add(key);
+        },
+    };
+}

package/dist/combat.d.ts

@@ -0,0 +1,34 @@
+export { createAbilityKit, type AbilityKit, type AbilitySlotSnapshot, type AbilitySlotState, } from "./combat/abilityKit.js";
+export { type AnimationClip, type FrameRange } from "./combat/animationState.js";
+export { attackMeta, counters, isBlockable, isDodgeable, isParryable } from "./combat/attackTags.js";
+export { createBuildupMeter, createStaggerMeter, type BuildupProc } from "./combat/breakMeters.js";
+export { createCastRunner } from "./combat/castRunner.js";
+export { createComboPoints } from "./combat/comboPoints.js";
+export { advanceCombo, createComboRunner, type ComboStep } from "./combat/comboString.js";
+export { MAX_INTERCEPT_STEPS, createAntiOneShotPolicy, createDamageClamp, createDamagePipeline, createImmunityWindow, resolveDamage, type AntiOneShotConfig, type AntiOneShotPolicy, type DamageClampConfig, type DamageInterceptor, type DamagePipeline, type DamageResolution, type ImmunityWindow, type InterceptContext, type InterceptDecision, type InterceptRecord, type PendingDamage, } from "./combat/damageInterceptors.js";
+export { resolveMatchup, type DamageChannelId, type DamageMatchup, type MatchupOutputs, type ResolvedMatchup, type TargetTraitId, } from "./combat/damageMatchup.js";
+export { resolveDamageHit, type DamageHitInput, type DamageHitResolution } from "./combat/damageResolution.js";
+export { createDeathSystem, type OnDeathSpec } from "./combat/death.js";
+export { type DeathReason } from "./combat/deathReason.js";
+export { createDefensiveWindow, resolveDefense } from "./combat/defensiveWindow.js";
+export { createDotField } from "./combat/dotField.js";
+export { createDownedState } from "./combat/downed.js";
+export { createEffectSystem, type ReceiveMap } from "./combat/effects.js";
+export { BUILTIN_COMPLETION_PREDICATES, BUILTIN_SPAWN_PROVIDERS, activePhaseId, createEncounterState, encounterProgress, forceCompletePhase, injectPhase, phaseStatus, startEncounter, updateEncounter, type CompletionPredicate, type EncounterConfig, type EncounterContext, type EncounterEvent, type EncounterPhase, type EncounterSignals, type EncounterSpawnRequest, type EncounterState, type EncounterStep, type PhaseCompletionRef, type PhaseInjectAt, type PhaseRuntime, type PhaseSpawnRef, type PhaseStatus, type PredicateContext, type SpawnProvider, type SpawnProviderContext, } from "./combat/encounterSequence.js";
+export { impactPresets, resolveHitReaction, type HitReactionConfig } from "./combat/hitReaction.js";
+export { createMagazine, type Magazine, type MagazineReserve } from "./combat/magazine.js";
+export { createProjectileSystem, type ObjectRaycastHit, type ProjectileSystemDeps, type RaycastHit, } from "./combat/projectiles.js";
+export { resolveReceivedDamage, type DamageContext, type DamagePredicate, type ReceivedDamageResult, type ReceivedModifier, type ReceivedPolicy, } from "./combat/receivedDamage.js";
+export { createRegenShield } from "./combat/regenShield.js";
+export { DEFAULT_FIRE_PULSE_SECONDS, DEFAULT_HIT_PULSE_SECONDS, DEFAULT_RENDER_CUES, advanceMotionCues, applyRenderAnimationEvent, applyRenderDeathEvent, applyRenderHitEvent, type EntityRenderCues, type RenderCueTuning, } from "./combat/renderCues.js";
+export { resistanceScale, resolveResistance } from "./combat/resistance.js";
+export { createResourcePool, type ResourcePool } from "./combat/resourcePool.js";
+export { allocateRewards, filterOutcomeFor, resolveClaim, type AllocationOutcome, type AllocationRequest, type ClaimOutcome, type ClaimablePool, type RewardClaimSpec, type RewardGrant, type RewardPolicyKind, type RewardRecipient, type RewardResult, type RewardShare, } from "./combat/rewardAllocation.js";
+export { DEFAULT_EYE_HEIGHT, convergeShot, eyeHeightFromColliders, resolveShot, type ShotOriginPolicy, } from "./combat/shotOrigin.js";
+export { resolveStatusApplication, type StatusApplicationOutcome, type StatusApplicationSpec, type StatusImmunity, type StatusInstance, type StatusStackPolicy, } from "./combat/statusApplication.js";
+export { type TelegraphConfig, type TelegraphShape } from "./combat/telegraph.js";
+export { createThresholdTracker, type CrossingDirection, type CrossingPolicy, type CrossingTrigger, type ThresholdCrossing, type ThresholdCrossingConfig, type ThresholdMark, type ThresholdTracker, type ThresholdTrackerSnapshot, } from "./combat/thresholdCrossings.js";
+export { createAccumulatorMeter, tierAt, type MeterAddResult } from "./stats/accumulatorMeter.js";
+export { createEventMeter, type EventMeter, type EventMeterFeedResult } from "./stats/eventMeter.js";
+export { rollCheck, type CheckAdvantage, type CheckResult } from "./stats/rollCheck.js";
+export { createStats, type Stats } from "./stats/statModifiers.js";

package/dist/combat.js

@@ -0,0 +1,34 @@
+export { createAbilityKit, } from "./combat/abilityKit.js";
+export {} from "./combat/animationState.js";
+export { attackMeta, counters, isBlockable, isDodgeable, isParryable } from "./combat/attackTags.js";
+export { createBuildupMeter, createStaggerMeter } from "./combat/breakMeters.js";
+export { createCastRunner } from "./combat/castRunner.js";
+export { createComboPoints } from "./combat/comboPoints.js";
+export { advanceCombo, createComboRunner } from "./combat/comboString.js";
+export { MAX_INTERCEPT_STEPS, createAntiOneShotPolicy, createDamageClamp, createDamagePipeline, createImmunityWindow, resolveDamage, } from "./combat/damageInterceptors.js";
+export { resolveMatchup, } from "./combat/damageMatchup.js";
+export { resolveDamageHit } from "./combat/damageResolution.js";
+export { createDeathSystem } from "./combat/death.js";
+export {} from "./combat/deathReason.js";
+export { createDefensiveWindow, resolveDefense } from "./combat/defensiveWindow.js";
+export { createDotField } from "./combat/dotField.js";
+export { createDownedState } from "./combat/downed.js";
+export { createEffectSystem } from "./combat/effects.js";
+export { BUILTIN_COMPLETION_PREDICATES, BUILTIN_SPAWN_PROVIDERS, activePhaseId, createEncounterState, encounterProgress, forceCompletePhase, injectPhase, phaseStatus, startEncounter, updateEncounter, } from "./combat/encounterSequence.js";
+export { impactPresets, resolveHitReaction } from "./combat/hitReaction.js";
+export { createMagazine } from "./combat/magazine.js";
+export { createProjectileSystem, } from "./combat/projectiles.js";
+export { resolveReceivedDamage, } from "./combat/receivedDamage.js";
+export { createRegenShield } from "./combat/regenShield.js";
+export { DEFAULT_FIRE_PULSE_SECONDS, DEFAULT_HIT_PULSE_SECONDS, DEFAULT_RENDER_CUES, advanceMotionCues, applyRenderAnimationEvent, applyRenderDeathEvent, applyRenderHitEvent, } from "./combat/renderCues.js";
+export { resistanceScale, resolveResistance } from "./combat/resistance.js";
+export { createResourcePool } from "./combat/resourcePool.js";
+export { allocateRewards, filterOutcomeFor, resolveClaim, } from "./combat/rewardAllocation.js";
+export { DEFAULT_EYE_HEIGHT, convergeShot, eyeHeightFromColliders, resolveShot, } from "./combat/shotOrigin.js";
+export { resolveStatusApplication, } from "./combat/statusApplication.js";
+export {} from "./combat/telegraph.js";
+export { createThresholdTracker, } from "./combat/thresholdCrossings.js";
+export { createAccumulatorMeter, tierAt } from "./stats/accumulatorMeter.js";
+export { createEventMeter } from "./stats/eventMeter.js";
+export { rollCheck } from "./stats/rollCheck.js";
+export { createStats } from "./stats/statModifiers.js";

package/dist/commands/commandRegistry.d.ts

@@ -1,7 +1,18 @@
 export interface CommandRejection {
     reason: string;
 }
+export type CommandDecodeResult<TInput> = {
+    ok: true;
+    value: TInput;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Parses raw `unknown` transport input into `TInput`, rejecting anything that doesn't match the command's declared shape. Runs before `validate`/`apply`, so a malformed payload never reaches game logic. */
+export type CommandDecoder<TInput> = (input: unknown) => CommandDecodeResult<TInput>;
 export interface CommandDefinition<TState, TInput> {
+    /** Runtime codec for this command's input. Declaring one turns the boundary strict: a payload that fails to decode is rejected before `validate`/`apply` ever see it. Omit to keep passing raw input through unchanged (existing behavior). */
+    decode?: CommandDecoder<TInput>;
     validate?(state: TState, input: TInput): CommandRejection | null;
     apply(state: TState, input: TInput): TState | void;
 }

package/dist/commands/commandRegistry.js

@@ -17,10 +17,17 @@ export function createCommandRegistry() {
             const definition = definitions.get(name);
             if (!definition)
                 return { status: "unknown-command" };
-            const rejection = definition.validate?.(state, input) ?? null;
+            let decoded = input;
+            if (definition.decode) {
+                const result = definition.decode(input);
+                if (!result.ok)
+                    return { status: "rejected", reason: result.reason };
+                decoded = result.value;
+            }
+            const rejection = definition.validate?.(state, decoded) ?? null;
             if (rejection)
                 return { status: "rejected", reason: rejection.reason };
-            const next = definition.apply(state, input);
+            const next = definition.apply(state, decoded);
             return { status: "applied", state: next === undefined ? state : next };
         },
     };

package/dist/crafting/crop.d.ts

@@ -16,36 +16,53 @@ export interface CropTileState {
     harvestable: boolean;
 }
 export type CropCatalog = (cropId: string) => CropDef | null;
+/** @internal */
 export declare function emptyTile(): CropTileState;
+/** @internal */
 export declare function canTill(state: CropTileState): boolean;
+/** @internal */
 export declare function tillTile(state: CropTileState): CropTileState;
+/** @internal */
 export declare function canPlant(state: CropTileState): boolean;
+/** @internal */
 export declare function plantCrop(state: CropTileState, cropId: string): CropTileState;
+/** @internal */
 export declare function waterTile(state: CropTileState): CropTileState;
+/** @internal */
 export declare function maturityDays(def: CropDef): number;
+/** @internal */
 export declare function advanceCropDay(def: CropDef, state: CropTileState): CropTileState;
 export interface HarvestResult {
     state: CropTileState;
     yield: RecipeItem | null;
 }
+/** @internal */
 export declare function harvestCrop(def: CropDef, state: CropTileState): HarvestResult;
 export type TileCoord = readonly [number, number];
 export type TilePattern = readonly TileCoord[];
+/** @internal */
 export declare function tileKey(coord: TileCoord): string;
+/** @internal */
 export declare function singleTile(): TilePattern;
+/** @internal */
 export declare function squarePattern(radius: number): TilePattern;
+/** @internal */
 export declare function diamondPattern(radius: number): TilePattern;
+/** @internal */
 export declare function rectPattern(width: number, depth: number): TilePattern;
+/** @internal */
 export declare function patternAt(center: TileCoord, pattern: TilePattern): TileCoord[];
 export interface ApplyToolResult {
     tiles: Map<string, CropTileState>;
     changed: TileCoord[];
 }
+/** @internal */
 export declare function applyToolToTiles(tiles: ReadonlyMap<string, CropTileState>, center: TileCoord, pattern: TilePattern, apply: (state: CropTileState, coord: TileCoord) => CropTileState, fill?: () => CropTileState): ApplyToolResult;
 export interface DayTicker {
     tick(currentDay: number): number;
     day(): number;
 }
+/** @internal */
 export declare function createDayTicker(startDay?: number): DayTicker;
 export interface CropField {
     get(coord: TileCoord): CropTileState;
@@ -56,4 +73,5 @@ export interface CropField {
     advanceDay(days?: number): void;
     tiles(): ReadonlyMap<string, CropTileState>;
 }
+/** @internal */
 export declare function createCropField(catalog?: CropCatalog): CropField;

package/dist/crafting/crop.js

@@ -1,30 +1,38 @@
+/** @internal */
 export function emptyTile() {
     return { soil: "untilled", watered: false, cropId: null, stage: 0, stageProgress: 0, harvestable: false };
 }
+/** @internal */
 export function canTill(state) {
     return state.soil === "untilled" && state.cropId === null;
 }
+/** @internal */
 export function tillTile(state) {
     if (!canTill(state))
         return state;
     return { ...state, soil: "tilled" };
 }
+/** @internal */
 export function canPlant(state) {
     return state.soil === "tilled" && state.cropId === null;
 }
+/** @internal */
 export function plantCrop(state, cropId) {
     if (!canPlant(state))
         return state;
     return { ...state, cropId, stage: 0, stageProgress: 0, harvestable: false };
 }
+/** @internal */
 export function waterTile(state) {
     if (state.soil !== "tilled" || state.watered)
         return state;
     return { ...state, watered: true };
 }
+/** @internal */
 export function maturityDays(def) {
     return def.stages.reduce((sum, days) => sum + Math.max(0, days), 0);
 }
+/** @internal */
 export function advanceCropDay(def, state) {
     const rested = state.watered ? { ...state, watered: false } : state;
     if (state.cropId === null)
@@ -49,6 +57,7 @@ export function advanceCropDay(def, state) {
     }
     return rested;
 }
+/** @internal */
 export function harvestCrop(def, state) {
     if (!state.harvestable || state.cropId === null)
         return { state, yield: null };
@@ -64,12 +73,15 @@ export function harvestCrop(def, state) {
         yield: produce,
     };
 }
+/** @internal */
 export function tileKey(coord) {
     return `${coord[0]},${coord[1]}`;
 }
+/** @internal */
 export function singleTile() {
     return [[0, 0]];
 }
+/** @internal */
 export function squarePattern(radius) {
     const r = Math.max(0, Math.floor(radius));
     const tiles = [];
@@ -78,6 +90,7 @@ export function squarePattern(radius) {
             tiles.push([dx, dz]);
     return tiles;
 }
+/** @internal */
 export function diamondPattern(radius) {
     const r = Math.max(0, Math.floor(radius));
     const tiles = [];
@@ -87,6 +100,7 @@ export function diamondPattern(radius) {
                 tiles.push([dx, dz]);
     return tiles;
 }
+/** @internal */
 export function rectPattern(width, depth) {
     const w = Math.max(1, Math.floor(width));
     const d = Math.max(1, Math.floor(depth));
@@ -98,9 +112,11 @@ export function rectPattern(width, depth) {
             tiles.push([x0 + dx, z0 + dz]);
     return tiles;
 }
+/** @internal */
 export function patternAt(center, pattern) {
     return pattern.map(([dx, dz]) => [center[0] + dx, center[1] + dz]);
 }
+/** @internal */
 export function applyToolToTiles(tiles, center, pattern, apply, fill = emptyTile) {
     const next = new Map(tiles);
     const changed = [];
@@ -115,6 +131,7 @@ export function applyToolToTiles(tiles, center, pattern, apply, fill = emptyTile
     }
     return { tiles: next, changed };
 }
+/** @internal */
 export function createDayTicker(startDay = 0) {
     let last = Math.floor(startDay);
     return {
@@ -127,6 +144,7 @@ export function createDayTicker(startDay = 0) {
         day: () => last,
     };
 }
+/** @internal */
 export function createCropField(catalog = () => null) {
     let grid = new Map();
     function read(coord) {

package/dist/crafting/production.d.ts

@@ -27,6 +27,11 @@ export interface ProductionTickInput {
     powered?: boolean;
 }
 export declare function productionBuilding(config: ProductionBuildingConfig): ProductionBuildingDef;
+/**
+ * A production building that converts input items into outputs over time — factory/crafting station.
+ *
+ * @capability production-building a factory building converting inputs to outputs over time
+ */
 export declare function createProductionState(): ProductionState;
 export declare function acceptsInput(def: ProductionBuildingDef, state: ProductionState, itemId: string): boolean;
 export declare function feedProduction(def: ProductionBuildingDef, state: ProductionState, itemId: string, count: number): {