@arcane-engine/runtime 0.1.0 → 0.2.1

package/src/state/query.ts

@@ -1,9 +1,34 @@
 import type { Vec2 } from "./types.ts";
 
-/** A predicate function for filtering */
+/**
+ * A predicate function for filtering state queries.
+ * Returns true if the item matches the filter criteria.
+ * Build predicates using combinators: {@link lt}, {@link gt}, {@link eq}, {@link oneOf}, etc.
+ */
 export type Predicate<T> = (item: T) => boolean;
 
-/** Query an array at a path, with optional filtering */
+/**
+ * Query state at a dot-separated path, with optional filtering.
+ * Pure function — does not modify the state.
+ *
+ * If the value at the path is an array, returns matching elements.
+ * If the value is a single value, wraps it in an array.
+ * If the path doesn't exist, returns an empty array.
+ *
+ * The filter can be a predicate function, or an object where each key-value pair
+ * must match (values can be predicates or literal values).
+ * Supports `*` wildcards in paths to query across array elements.
+ *
+ * @param state - The state to query.
+ * @param path - Dot-separated path (e.g., "enemies", "player.inventory"). Use `*` for wildcards.
+ * @param filter - Optional predicate function or property-matching object.
+ * @returns Readonly array of matching results.
+ *
+ * @example
+ * const alive = query(state, "enemies", { alive: true });
+ * const nearby = query(state, "enemies", within({ x: 5, y: 5 }, 3));
+ * const names = query(state, "enemies.*.name");
+ */
 export function query<S, R = unknown>(
   state: S,
   path: string,
@@ -36,12 +61,30 @@ export function query<S, R = unknown>(
   }) as readonly R[];
 }
 
-/** Get a single value at a path */
+/**
+ * Get a single value at a dot-separated path. Pure function.
+ * Returns undefined if the path doesn't exist.
+ *
+ * @param state - The state to read from.
+ * @param path - Dot-separated path (e.g., "player.hp", "config.difficulty").
+ * @returns The value at the path, or undefined if not found.
+ *
+ * @example
+ * const hp = get(state, "player.hp"); // number | undefined
+ */
 export function get<S, R = unknown>(state: S, path: string): R | undefined {
   return getByPath(state, path) as R | undefined;
 }
 
-/** Check existence at a path, optionally with a predicate */
+/**
+ * Check if a value exists at a path, optionally testing it with a predicate.
+ * Pure function. Returns false if the path doesn't exist or if the predicate fails.
+ *
+ * @param state - The state to check.
+ * @param path - Dot-separated path (e.g., "player.weapon").
+ * @param predicate - Optional predicate to test the value against.
+ * @returns True if the value exists (and passes the predicate, if provided).
+ */
 export function has<S>(
   state: S,
   path: string,
@@ -55,42 +98,84 @@ export function has<S>(
 
 // --- Filter combinators ---
 
-/** Less than */
+/**
+ * Create a predicate that tests if a number is less than the given value.
+ *
+ * @param value - The threshold to compare against.
+ * @returns A predicate returning true if item < value.
+ */
 export function lt(value: number): Predicate<number> {
   return (item: number) => item < value;
 }
 
-/** Greater than */
+/**
+ * Create a predicate that tests if a number is greater than the given value.
+ *
+ * @param value - The threshold to compare against.
+ * @returns A predicate returning true if item > value.
+ */
 export function gt(value: number): Predicate<number> {
   return (item: number) => item > value;
 }
 
-/** Less than or equal */
+/**
+ * Create a predicate that tests if a number is less than or equal to the given value.
+ *
+ * @param value - The threshold to compare against.
+ * @returns A predicate returning true if item <= value.
+ */
 export function lte(value: number): Predicate<number> {
   return (item: number) => item <= value;
 }
 
-/** Greater than or equal */
+/**
+ * Create a predicate that tests if a number is greater than or equal to the given value.
+ *
+ * @param value - The threshold to compare against.
+ * @returns A predicate returning true if item >= value.
+ */
 export function gte(value: number): Predicate<number> {
   return (item: number) => item >= value;
 }
 
-/** Strict equality */
+/**
+ * Create a predicate that tests for strict equality (===) with the given value.
+ *
+ * @param value - The value to compare against.
+ * @returns A predicate returning true if item === value.
+ */
 export function eq<T>(value: T): Predicate<T> {
   return (item: T) => item === value;
 }
 
-/** Not equal */
+/**
+ * Create a predicate that tests for strict inequality (!==) with the given value.
+ *
+ * @param value - The value to compare against.
+ * @returns A predicate returning true if item !== value.
+ */
 export function neq<T>(value: T): Predicate<T> {
   return (item: T) => item !== value;
 }
 
-/** Value is one of the given options */
+/**
+ * Create a predicate that tests if a value is one of the given options (using Array.includes).
+ *
+ * @param values - The allowed values to match against.
+ * @returns A predicate returning true if item is in the values list.
+ */
 export function oneOf<T>(...values: T[]): Predicate<T> {
   return (item: T) => values.includes(item);
 }
 
-/** Position within radius of a center point */
+/**
+ * Create a predicate that tests if a Vec2 position is within a circular radius
+ * of a center point. Uses squared distance for efficiency (no sqrt).
+ *
+ * @param center - Center point of the circle.
+ * @param radius - Radius of the circle. Must be >= 0.
+ * @returns A predicate returning true if the position is within the circle (inclusive).
+ */
 export function within(center: Vec2, radius: number): Predicate<Vec2> {
   return (pos: Vec2) => {
     const dx = pos.x - center.x;
@@ -99,17 +184,32 @@ export function within(center: Vec2, radius: number): Predicate<Vec2> {
   };
 }
 
-/** Combine predicates: all must pass */
+/**
+ * Combine multiple predicates with logical AND. All predicates must pass.
+ *
+ * @param predicates - Predicates to combine.
+ * @returns A predicate returning true only if every predicate passes.
+ */
 export function allOf<T>(...predicates: Predicate<T>[]): Predicate<T> {
   return (item: T) => predicates.every((p) => p(item));
 }
 
-/** Combine predicates: any must pass */
+/**
+ * Combine multiple predicates with logical OR. At least one predicate must pass.
+ *
+ * @param predicates - Predicates to combine.
+ * @returns A predicate returning true if any predicate passes.
+ */
 export function anyOf<T>(...predicates: Predicate<T>[]): Predicate<T> {
   return (item: T) => predicates.some((p) => p(item));
 }
 
-/** Negate a predicate */
+/**
+ * Negate a predicate. Returns the logical NOT of the original predicate.
+ *
+ * @param predicate - The predicate to negate.
+ * @returns A predicate returning true when the original returns false, and vice versa.
+ */
 export function not<T>(predicate: Predicate<T>): Predicate<T> {
   return (item: T) => !predicate(item);
 }

package/src/state/store.ts

@@ -6,47 +6,78 @@ import { query, get, has } from "./query.ts";
 import type { PathPattern, ObserverCallback, Unsubscribe } from "./observe.ts";
 import { createObserverRegistry } from "./observe.ts";
 
-/** The game store: ties state + transactions + observers together */
+/**
+ * The game store: central coordination point for state management.
+ * Ties together state, transactions, queries, and observers.
+ * Created via {@link createStore}.
+ *
+ * - `getState()` - Returns the current state as a deep readonly snapshot.
+ * - `dispatch(mutations)` - Apply mutations atomically, update state, notify observers.
+ * - `observe(pattern, callback)` - Subscribe to state changes matching a path pattern.
+ * - `query(path, filter?)` - Query arrays or values in current state.
+ * - `get(path)` - Get a single value from current state.
+ * - `has(path, predicate?)` - Check existence in current state.
+ * - `replaceState(state)` - Replace the entire state (for deserialization / time travel).
+ * - `getHistory()` - Get the transaction history for recording/replay.
+ */
 export type GameStore<S> = Readonly<{
-  /** Current state (readonly snapshot) */
+  /** Returns the current state as a deep readonly snapshot. */
   getState: () => DeepReadonly<S>;
 
-  /** Apply mutations as a transaction, update state, notify observers */
+  /** Apply mutations atomically. Updates state and notifies observers on success. */
   dispatch: (mutations: readonly Mutation<S>[]) => TransactionResult<S>;
 
-  /** Subscribe to state changes at a path pattern */
+  /** Subscribe to state changes matching a path pattern. Returns an unsubscribe function. */
   observe: <T = unknown>(
     pattern: PathPattern,
     callback: ObserverCallback<T>,
   ) => Unsubscribe;
 
-  /** Query current state */
+  /** Query arrays or values at a path, with optional filtering. */
   query: <R = unknown>(
     path: string,
     filter?: Predicate<R> | Record<string, unknown>,
   ) => readonly R[];
 
-  /** Get a value from current state */
+  /** Get a single value from current state by path. Returns undefined if not found. */
   get: <R = unknown>(path: string) => R | undefined;
 
-  /** Check existence in current state */
+  /** Check if a value exists at a path, optionally testing with a predicate. */
   has: (path: string, predicate?: Predicate<unknown>) => boolean;
 
-  /** Replace the entire state (for deserialization / time travel) */
+  /** Replace the entire state (for deserialization / time travel). Does not trigger observers. */
   replaceState: (state: S) => void;
 
-  /** Get the transaction history (for recording/replay) */
+  /** Get the transaction history as an ordered list of TransactionRecords. */
   getHistory: () => readonly TransactionRecord<S>[];
 }>;
 
-/** A recorded transaction for replay */
+/**
+ * A recorded transaction for replay and debugging.
+ * Stored in the store's history, accessible via getHistory().
+ *
+ * - `timestamp` - When the transaction was applied (Date.now() milliseconds).
+ * - `mutations` - The mutations that were applied in this transaction.
+ * - `diff` - The computed diff of changes from this transaction.
+ */
 export type TransactionRecord<S> = Readonly<{
   timestamp: number;
   mutations: readonly Mutation<S>[];
   diff: Diff;
 }>;
 
-/** Create a game store with initial state */
+/**
+ * Create a new game store with initial state, transactions, and observers.
+ * The store is the central coordination point for game state management.
+ *
+ * @param initialState - The initial state object. Becomes the starting state for all queries.
+ * @returns A GameStore with getState, dispatch, observe, query, get, has, replaceState, and getHistory.
+ *
+ * @example
+ * const store = createStore({ player: { x: 0, y: 0, hp: 100 }, enemies: [] });
+ * store.dispatch([set("player.x", 10)]);
+ * console.log(store.getState().player.x); // 10
+ */
 export function createStore<S>(initialState: S): GameStore<S> {
   let state: S = initialState;
   const observers = createObserverRegistry<S>();

package/src/state/transaction.ts

@@ -1,7 +1,16 @@
 import type { ArcaneError } from "./error.ts";
 import { createError } from "./error.ts";
 
-/** A mutation: a named, describable, applicable state change */
+/**
+ * A mutation: a named, describable, applicable state change.
+ * Created by mutation primitives ({@link set}, {@link update}, {@link push}, etc.)
+ * and applied atomically via {@link transaction}.
+ *
+ * - `type` - Mutation kind: "set", "update", "push", or "remove".
+ * - `path` - Dot-separated path to the target value (e.g., "player.hp").
+ * - `description` - Human-readable description of what this mutation does.
+ * - `apply` - Pure function that takes state and returns new state with the mutation applied.
+ */
 export type Mutation<S> = Readonly<{
   type: string;
   path: string;
@@ -11,7 +20,21 @@ export type Mutation<S> = Readonly<{
 
 // --- Core mutation primitives ---
 
-/** Set a value at a path */
+/**
+ * Create a mutation that sets a value at a dot-separated path.
+ * Pure function — returns a Mutation object, does not modify state directly.
+ * Apply via {@link transaction} or {@link GameStore.dispatch}.
+ *
+ * @param path - Dot-separated path (e.g., "player.hp", "enemies.0.alive").
+ * @param value - The value to set at the path.
+ * @returns A Mutation that can be applied in a transaction.
+ *
+ * @example
+ * const result = transaction(state, [
+ *   set("player.hp", 80),
+ *   set("player.position.x", 10),
+ * ]);
+ */
 export function set<S>(path: string, value: unknown): Mutation<S> {
   return {
     type: "set",
@@ -21,7 +44,15 @@ export function set<S>(path: string, value: unknown): Mutation<S> {
   };
 }
 
-/** Update a value at a path with a function */
+/**
+ * Create a mutation that updates a value at a path using a transform function.
+ * The function receives the current value and returns the new value.
+ * Pure function — returns a Mutation object, does not modify state directly.
+ *
+ * @param path - Dot-separated path to the value (e.g., "player.hp").
+ * @param fn - Transform function: receives the current value, returns the new value.
+ * @returns A Mutation that can be applied in a transaction.
+ */
 export function update<S>(
   path: string,
   fn: (current: unknown) => unknown,
@@ -37,7 +68,14 @@ export function update<S>(
   };
 }
 
-/** Push an item onto an array at a path */
+/**
+ * Create a mutation that pushes an item onto an array at a path.
+ * Throws during application if the value at the path is not an array.
+ *
+ * @param path - Dot-separated path to the array (e.g., "enemies", "player.inventory").
+ * @param item - The item to append to the array.
+ * @returns A Mutation that can be applied in a transaction.
+ */
 export function push<S>(path: string, item: unknown): Mutation<S> {
   return {
     type: "push",
@@ -53,7 +91,14 @@ export function push<S>(path: string, item: unknown): Mutation<S> {
   };
 }
 
-/** Remove items from an array at a path matching a predicate */
+/**
+ * Create a mutation that removes items from an array at a path where the predicate returns true.
+ * Throws during application if the value at the path is not an array.
+ *
+ * @param path - Dot-separated path to the array.
+ * @param predicate - Function that returns true for items to remove.
+ * @returns A Mutation that can be applied in a transaction.
+ */
 export function removeWhere<S>(
   path: string,
   predicate: (item: unknown) => boolean,
@@ -76,7 +121,15 @@ export function removeWhere<S>(
   };
 }
 
-/** Remove a key from an object at a path */
+/**
+ * Create a mutation that removes a key from an object.
+ * The last segment of the path is the key to remove; the preceding segments
+ * identify the parent object. Throws during application if the parent is not an object.
+ *
+ * @param path - Dot-separated path where the last segment is the key to remove
+ *               (e.g., "player.buffs.shield" removes "shield" from player.buffs).
+ * @returns A Mutation that can be applied in a transaction.
+ */
 export function removeKey<S>(path: string): Mutation<S> {
   const segments = path.split(".");
   const key = segments.pop()!;
@@ -101,28 +154,54 @@ export function removeKey<S>(path: string): Mutation<S> {
 
 // --- Diff ---
 
-/** A single change entry */
+/**
+ * A single change entry in a diff, representing one value that changed.
+ *
+ * - `path` - Dot-separated path to the changed value (e.g., "player.hp").
+ * - `from` - The previous value (undefined if the key was added).
+ * - `to` - The new value (undefined if the key was removed).
+ */
 export type DiffEntry = Readonly<{
   path: string;
   from: unknown;
   to: unknown;
 }>;
 
-/** All changes from a transaction */
+/**
+ * All changes from a transaction, as a list of individual DiffEntry items.
+ * Empty entries array means no changes occurred.
+ *
+ * - `entries` - Ordered list of individual value changes.
+ */
 export type Diff = Readonly<{
   entries: readonly DiffEntry[];
 }>;
 
 // --- Transaction result ---
 
-/** An effect triggered by a state change (for observer/event routing) */
+/**
+ * An effect triggered by a state change, for observer/event routing.
+ * Reserved for future use — currently transactions return an empty effects array.
+ *
+ * - `type` - Effect type identifier (e.g., "damage", "levelUp").
+ * - `source` - Identifier of the mutation or system that produced this effect.
+ * - `data` - Arbitrary payload data for the effect.
+ */
 export type Effect = Readonly<{
   type: string;
   source: string;
   data: Readonly<Record<string, unknown>>;
 }>;
 
-/** Result of executing a transaction */
+/**
+ * Result of executing a transaction. Check `valid` before using the new state.
+ *
+ * - `state` - The resulting state. Equals the original state if the transaction failed.
+ * - `diff` - Changes that occurred. Empty if the transaction failed.
+ * - `effects` - Side effects produced (reserved for future use).
+ * - `valid` - Whether the transaction succeeded. If false, state is unchanged.
+ * - `error` - Structured error if `valid` is false. Undefined on success.
+ */
 export type TransactionResult<S> = Readonly<{
   state: S;
   diff: Diff;
@@ -131,7 +210,24 @@ export type TransactionResult<S> = Readonly<{
   error?: ArcaneError;
 }>;
 
-/** Apply mutations atomically. All succeed or all roll back. */
+/**
+ * Apply mutations atomically to state. All succeed or all roll back.
+ * Pure function — returns a new state without modifying the original.
+ * If any mutation throws, the entire transaction fails and the original state is returned.
+ *
+ * @param state - The current state to apply mutations to.
+ * @param mutations - Ordered list of mutations to apply. Created via {@link set}, {@link update}, etc.
+ * @returns A TransactionResult with the new state, diff, and validity flag.
+ *
+ * @example
+ * const result = transaction(state, [
+ *   set("player.hp", 80),
+ *   update("player.xp", (xp: any) => xp + 50),
+ * ]);
+ * if (result.valid) {
+ *   // Use result.state
+ * }
+ */
 export function transaction<S>(
   state: S,
   mutations: readonly Mutation<S>[],
@@ -166,7 +262,15 @@ export function transaction<S>(
   }
 }
 
-/** Compute the diff between two state trees */
+/**
+ * Compute the diff between two state trees by recursively comparing all values.
+ * Pure function — does not modify either state tree.
+ * Used internally by {@link transaction}, but can also be called directly.
+ *
+ * @param before - The state before changes.
+ * @param after - The state after changes.
+ * @returns A Diff containing all individual value changes.
+ */
 export function computeDiff<S>(before: S, after: S): Diff {
   const entries: DiffEntry[] = [];
   diffRecursive(before, after, "", entries);

package/src/state/types.ts

@@ -1,22 +1,48 @@
-/** Branded string type for entity identification */
+/**
+ * Branded string type for entity identification.
+ * Uses TypeScript's structural branding to prevent plain strings from being
+ * used where an EntityId is expected. Create via {@link entityId} or {@link generateId}.
+ */
 export type EntityId = string & { readonly __entityId: true };
 
-/** Create an EntityId from a string */
+/**
+ * Create an EntityId from a known string value.
+ * Use this for deterministic IDs (e.g., "player", "enemy_1").
+ * For random unique IDs, use {@link generateId} instead.
+ *
+ * @param id - The string to brand as an EntityId.
+ * @returns A branded EntityId.
+ */
 export function entityId(id: string): EntityId {
   return id as EntityId;
 }
 
-/** Generate a unique EntityId (uses crypto.randomUUID or counter in tests) */
+/**
+ * Generate a unique EntityId using crypto.randomUUID().
+ * Each call produces a new UUID v4 string branded as EntityId.
+ * Use {@link entityId} instead when you need a deterministic, human-readable ID.
+ *
+ * @returns A new unique EntityId.
+ */
 export function generateId(): EntityId {
   return crypto.randomUUID() as EntityId;
 }
 
-/** 2D position vector (immutable) */
+/**
+ * Immutable 2D vector. Used for positions, velocities, and directions.
+ *
+ * - `x` - Horizontal component (positive = right).
+ * - `y` - Vertical component (positive = down in screen coordinates).
+ */
 export type Vec2 = Readonly<{ x: number; y: number }>;
 
 type Primitive = string | number | boolean | null | undefined;
 
-/** Deep recursive readonly — enforces immutability at the type level */
+/**
+ * Deep recursive readonly utility type. Enforces immutability at the type level
+ * by recursively wrapping all properties, arrays, Maps, and Sets as readonly.
+ * Applied to state returned by {@link GameStore.getState} to prevent accidental mutation.
+ */
 export type DeepReadonly<T> = T extends Primitive
   ? T
   : T extends (infer U)[]

package/src/systems/system.ts

@@ -1,7 +1,26 @@
 import type { Condition, Action, Rule, SystemDef, RuleResult, ExtendOptions } from "./types.ts";
 import { createError } from "../state/error.ts";
 
-/** Create a system definition from a name and list of rules. */
+/**
+ * Create a system definition from a name and list of rules.
+ *
+ * A system is a named collection of rules that together define a game mechanic.
+ * Use {@link rule} to build rules, then combine them into a system.
+ *
+ * @typeParam S - The game state type.
+ * @param name - System name (e.g., "combat", "inventory").
+ * @param rules - Ordered array of rules belonging to this system.
+ * @returns An immutable {@link SystemDef}.
+ *
+ * @example
+ * ```ts
+ * const combat = system("combat", [
+ *   rule<GameState>("attack")
+ *     .when((s, args) => s.player.hp > 0)
+ *     .then((s, args) => ({ ...s, enemy: { ...s.enemy, hp: s.enemy.hp - 10 } })),
+ * ]);
+ * ```
+ */
 export function system<S>(name: string, rules: readonly Rule<S>[]): SystemDef<S> {
   return { name, rules };
 }
@@ -21,7 +40,24 @@ type RuleBuilderBase<S> = {
   };
 };
 
-/** Fluent builder for creating rules. */
+/**
+ * Fluent builder for creating named rules.
+ *
+ * Chain `.when()` to add conditions and `.then()` to add actions.
+ * Use `.replaces()` to mark this rule as a replacement for an existing rule
+ * when used with {@link extend}.
+ *
+ * @typeParam S - The game state type.
+ * @param name - Unique rule name within the system.
+ * @returns A fluent builder with `.when()`, `.then()`, and `.replaces()` methods.
+ *
+ * @example
+ * ```ts
+ * const attackRule = rule<GameState>("attack")
+ *   .when((s) => s.player.hp > 0, (s) => s.enemy.hp > 0)
+ *   .then((s, args) => ({ ...s, enemy: { ...s.enemy, hp: s.enemy.hp - 10 } }));
+ * ```
+ */
 export function rule<S>(name: string): RuleBuilderBase<S> {
   let replacesName: string | undefined;
 
@@ -59,7 +95,20 @@ export function rule<S>(name: string): RuleBuilderBase<S> {
   };
 }
 
-/** Find a rule by name, apply conditions, chain actions. */
+/**
+ * Find a rule by name in a system, check its conditions, and execute its actions.
+ *
+ * If the rule is not found, returns `{ ok: false }` with an UNKNOWN_RULE error.
+ * If any condition fails, returns `{ ok: false }` with a CONDITION_FAILED error.
+ * Otherwise, chains all actions and returns `{ ok: true }` with the new state.
+ *
+ * @typeParam S - The game state type.
+ * @param sys - The system to search for the rule.
+ * @param ruleName - Name of the rule to apply.
+ * @param state - Current game state.
+ * @param args - Optional arguments passed to conditions and actions.
+ * @returns A {@link RuleResult} with the outcome and resulting state.
+ */
 export function applyRule<S>(
   sys: SystemDef<S>,
   ruleName: string,
@@ -102,7 +151,16 @@ export function applyRule<S>(
   return { ok: true, state: current, ruleName };
 }
 
-/** Return names of rules whose conditions are all met. */
+/**
+ * Return names of rules whose conditions are all satisfied for the given state.
+ * Useful for presenting valid actions to a player or AI agent.
+ *
+ * @typeParam S - The game state type.
+ * @param sys - The system to query.
+ * @param state - Current game state to test conditions against.
+ * @param args - Optional arguments passed to condition functions.
+ * @returns Array of rule names that can currently be applied.
+ */
 export function getApplicableRules<S>(
   sys: SystemDef<S>,
   state: S,
@@ -113,7 +171,21 @@ export function getApplicableRules<S>(
     .map((r) => r.name);
 }
 
-/** Extend a system: replace rules by name, add new rules, remove rules by name. */
+/**
+ * Create a new system by extending an existing one.
+ *
+ * Supports three operations:
+ * 1. **Replace** — new rules with `replaces` set swap out existing rules by name.
+ * 2. **Add** — new rules without `replaces` are appended to the end.
+ * 3. **Remove** — rules named in `options.remove` are excluded.
+ *
+ * The base system is not modified; a new {@link SystemDef} is returned.
+ *
+ * @typeParam S - The game state type.
+ * @param base - The system to extend.
+ * @param options - Rules to add/replace and rule names to remove.
+ * @returns A new system with the modifications applied.
+ */
 export function extend<S>(base: SystemDef<S>, options: ExtendOptions<S>): SystemDef<S> {
   const removeSet = new Set(options.remove ?? []);
   const newRules = options.rules ?? [];