@sharpee/stdlib 0.9.60-beta

package/dist/actions/enhanced-types.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Enhanced action system types
+ *
+ * This provides a cleaner, more author-friendly action system while
+ * maintaining the event-driven architecture. Actions return events,
+ * but the enhanced context makes it easy to create those events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EventTypes = exports.MessageNamespaces = exports.ScopeErrors = void 0;
+/**
+ * Standard error codes for scope failures.
+ * These map to message IDs in the language layer.
+ */
+exports.ScopeErrors = {
+    /** Entity is completely unknown to the player */
+    NOT_KNOWN: 'scope.not_known',
+    /** Entity is known but not currently visible */
+    NOT_VISIBLE: 'scope.not_visible',
+    /** Entity is visible but not physically reachable */
+    NOT_REACHABLE: 'scope.not_reachable',
+    /** Entity must be carried but is not in inventory */
+    NOT_CARRIED: 'scope.not_carried',
+    /** Generic scope failure */
+    OUT_OF_SCOPE: 'scope.out_of_scope'
+};
+/**
+ * Standard message namespaces
+ */
+exports.MessageNamespaces = {
+    SYSTEM: 'if.system',
+    ACTION: 'if.action',
+    ERROR: 'if.error',
+    GAME: 'if.game',
+    STORY: 'story',
+    EXTENSION: 'ext'
+};
+/**
+ * Standard event types
+ */
+exports.EventTypes = {
+    TEXT: 'text',
+    ACTION_SUCCESS: 'action.success',
+    ACTION_ERROR: 'action.error',
+    ACTION_FAILED: 'action.failed',
+    GAME_MESSAGE: 'game.message',
+    SYSTEM_MESSAGE: 'system.message'
+};
+//# sourceMappingURL=enhanced-types.js.map

package/dist/actions/enhanced-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enhanced-types.js","sourceRoot":"","sources":["../../src/actions/enhanced-types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AA+BH;;;GAGG;AACU,QAAA,WAAW,GAAG;IACzB,iDAAiD;IACjD,SAAS,EAAE,iBAAiB;IAE5B,gDAAgD;IAChD,WAAW,EAAE,mBAAmB;IAEhC,qDAAqD;IACrD,aAAa,EAAE,qBAAqB;IAEpC,qDAAqD;IACrD,WAAW,EAAE,mBAAmB;IAEhC,4BAA4B;IAC5B,YAAY,EAAE,oBAAoB;CAC1B,CAAC;AAgsBX;;GAEG;AACU,QAAA,iBAAiB,GAAG;IAC/B,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,WAAW;IACnB,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,OAAO;IACd,SAAS,EAAE,KAAK;CACR,CAAC;AAEX;;GAEG;AACU,QAAA,UAAU,GAAG;IACxB,IAAI,EAAE,MAAM;IACZ,cAAc,EAAE,gBAAgB;IAChC,YAAY,EAAE,cAAc;IAC5B,aAAa,EAAE,eAAe;IAC9B,YAAY,EAAE,cAAc;IAC5B,cAAc,EAAE,gBAAgB;CACxB,CAAC"}

package/dist/actions/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Actions module exports
+ */
+export * from './enhanced-types';
+export * from './enhanced-context';
+export { MetaAction } from './meta-action';
+export { MetaCommandRegistry } from './meta-registry';
+export * from './context';
+export * from './registry';
+export * from './constants';
+export * from './standard';
+export * from './author';
+export { createEvent } from '@sharpee/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/actions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AAGnC,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,cAAc,WAAW,CAAC;AAC1B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAG5B,cAAc,YAAY,CAAC;AAG3B,cAAc,UAAU,CAAC;AAGzB,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/actions/index.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Actions module exports
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEvent = exports.MetaCommandRegistry = exports.MetaAction = void 0;
+// Core types - export enhanced types as the primary interface
+__exportStar(require("./enhanced-types"), exports);
+__exportStar(require("./enhanced-context"), exports);
+// Meta-command support
+var meta_action_1 = require("./meta-action");
+Object.defineProperty(exports, "MetaAction", { enumerable: true, get: function () { return meta_action_1.MetaAction; } });
+var meta_registry_1 = require("./meta-registry");
+Object.defineProperty(exports, "MetaCommandRegistry", { enumerable: true, get: function () { return meta_registry_1.MetaCommandRegistry; } });
+// Implementation
+__exportStar(require("./context"), exports);
+__exportStar(require("./registry"), exports);
+__exportStar(require("./constants"), exports);
+// Standard actions
+__exportStar(require("./standard"), exports);
+// Author/debug actions
+__exportStar(require("./author"), exports);
+// Helper functions
+var core_1 = require("@sharpee/core");
+Object.defineProperty(exports, "createEvent", { enumerable: true, get: function () { return core_1.createEvent; } });
+//# sourceMappingURL=index.js.map

package/dist/actions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/actions/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;;;;;;;;;;;;;;;AAEH,8DAA8D;AAC9D,mDAAiC;AACjC,qDAAmC;AAEnC,uBAAuB;AACvB,6CAA2C;AAAlC,yGAAA,UAAU,OAAA;AACnB,iDAAsD;AAA7C,oHAAA,mBAAmB,OAAA;AAE5B,iBAAiB;AACjB,4CAA0B;AAC1B,6CAA2B;AAC3B,8CAA4B;AAE5B,mBAAmB;AACnB,6CAA2B;AAE3B,uBAAuB;AACvB,2CAAyB;AAEzB,mBAAmB;AACnB,sCAA4C;AAAnC,mGAAA,WAAW,OAAA"}

package/dist/actions/meta-action.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Meta-Action Base Class
+ *
+ * Base class for meta-commands (out-of-world actions) that don't affect game state.
+ * Meta-commands do not:
+ * - Increment the turn counter
+ * - Trigger NPC actions or daemons
+ * - Get recorded in command history
+ * - Affect the game world state
+ *
+ * Examples include debug commands, system commands (SAVE/RESTORE), and information
+ * commands (SCORE/VERSION).
+ */
+import { Action, ActionContext, ValidationResult } from './enhanced-types';
+import { ISemanticEvent } from '@sharpee/core';
+/**
+ * Abstract base class for meta-commands
+ *
+ * Extends this class to create commands that interact with the game system
+ * rather than the game world. The constructor automatically registers the
+ * command as a meta-command.
+ *
+ * @example
+ * ```typescript
+ * export class ScoreAction extends MetaAction {
+ *   id = 'score';
+ *   verbs = ['score'];
+ *
+ *   execute(context: ActionContext): ISemanticEvent[] {
+ *     // Display score without incrementing turn
+ *     return [
+ *       context.event('game.score', {
+ *         score: context.world.getStateValue('score') || 0
+ *       })
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class MetaAction implements Action {
+    /**
+     * Unique identifier for this action
+     */
+    abstract id: string;
+    /**
+     * Verbs that trigger this action
+     */
+    abstract verbs: string[];
+    /**
+     * Validate whether this meta-action can be executed
+     *
+     * Meta-actions typically have minimal validation requirements.
+     * Override this method for custom validation logic.
+     *
+     * @param context The action context
+     * @returns Validation result (defaults to always valid)
+     */
+    validate(context: ActionContext): ValidationResult;
+    /**
+     * @deprecated Use validate() instead. This will be removed after refactoring.
+     * Optional method to check if action can execute
+     * Override for complex conditions beyond verb matching
+     */
+    canExecute?(context: ActionContext): boolean;
+    /**
+     * Message ID for action description (for help/documentation)
+     */
+    descriptionMessageId?: string;
+    /**
+     * Message ID for example commands (for help/documentation)
+     */
+    examplesMessageId?: string;
+    /**
+     * Action group (for organizing related actions)
+     */
+    group?: string;
+    /**
+     * Priority for pattern matching (higher = preferred)
+     * Default is 0
+     */
+    priority?: number;
+    /**
+     * Constructor - subclasses should call ensureRegistered() after setting id
+     */
+    constructor();
+    /**
+     * Execute the meta-command
+     *
+     * @param context The action context
+     * @returns Array of semantic events
+     */
+    abstract execute(context: ActionContext): ISemanticEvent[];
+    /**
+     * Register this action as a meta-command
+     * Subclasses should call this after setting the id property
+     *
+     * @example
+     * ```typescript
+     * export class ScoreAction extends MetaAction {
+     *   id = 'score';
+     *   verbs = ['score'];
+     *
+     *   constructor() {
+     *     super();
+     *     this.ensureRegistered();
+     *   }
+     * }
+     * ```
+     */
+    protected ensureRegistered(): void;
+}
+//# sourceMappingURL=meta-action.d.ts.map

package/dist/actions/meta-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-action.d.ts","sourceRoot":"","sources":["../../src/actions/meta-action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,8BAAsB,UAAW,YAAW,MAAM;IAChD;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAEzB;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,gBAAgB;IAMlD;;;;OAIG;IACH,UAAU,CAAC,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO;IAE5C;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;;IAKH;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,aAAa,GAAG,cAAc,EAAE;IAE1D;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,gBAAgB,IAAI,IAAI;CAOnC"}

package/dist/actions/meta-action.js

@@ -0,0 +1,107 @@
+"use strict";
+/**
+ * Meta-Action Base Class
+ *
+ * Base class for meta-commands (out-of-world actions) that don't affect game state.
+ * Meta-commands do not:
+ * - Increment the turn counter
+ * - Trigger NPC actions or daemons
+ * - Get recorded in command history
+ * - Affect the game world state
+ *
+ * Examples include debug commands, system commands (SAVE/RESTORE), and information
+ * commands (SCORE/VERSION).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetaAction = void 0;
+const meta_registry_1 = require("./meta-registry");
+/**
+ * Abstract base class for meta-commands
+ *
+ * Extends this class to create commands that interact with the game system
+ * rather than the game world. The constructor automatically registers the
+ * command as a meta-command.
+ *
+ * @example
+ * ```typescript
+ * export class ScoreAction extends MetaAction {
+ *   id = 'score';
+ *   verbs = ['score'];
+ *
+ *   execute(context: ActionContext): ISemanticEvent[] {
+ *     // Display score without incrementing turn
+ *     return [
+ *       context.event('game.score', {
+ *         score: context.world.getStateValue('score') || 0
+ *       })
+ *     ];
+ *   }
+ * }
+ * ```
+ */
+class MetaAction {
+    /**
+     * Validate whether this meta-action can be executed
+     *
+     * Meta-actions typically have minimal validation requirements.
+     * Override this method for custom validation logic.
+     *
+     * @param context The action context
+     * @returns Validation result (defaults to always valid)
+     */
+    validate(context) {
+        // Meta-actions are generally always valid to execute
+        // Subclasses can override for specific validation needs
+        return { valid: true };
+    }
+    /**
+     * Message ID for action description (for help/documentation)
+     */
+    descriptionMessageId;
+    /**
+     * Message ID for example commands (for help/documentation)
+     */
+    examplesMessageId;
+    /**
+     * Action group (for organizing related actions)
+     */
+    group;
+    /**
+     * Priority for pattern matching (higher = preferred)
+     * Default is 0
+     */
+    priority;
+    /**
+     * Constructor - subclasses should call ensureRegistered() after setting id
+     */
+    constructor() {
+        // Subclass must call ensureRegistered() after setting properties
+    }
+    /**
+     * Register this action as a meta-command
+     * Subclasses should call this after setting the id property
+     *
+     * @example
+     * ```typescript
+     * export class ScoreAction extends MetaAction {
+     *   id = 'score';
+     *   verbs = ['score'];
+     *
+     *   constructor() {
+     *     super();
+     *     this.ensureRegistered();
+     *   }
+     * }
+     * ```
+     */
+    ensureRegistered() {
+        if (this.id) {
+            meta_registry_1.MetaCommandRegistry.register(this.id);
+        }
+        else {
+            console.warn('MetaAction: Cannot register without an id');
+        }
+    }
+}
+exports.MetaAction = MetaAction;
+//# sourceMappingURL=meta-action.js.map

package/dist/actions/meta-action.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-action.js","sourceRoot":"","sources":["../../src/actions/meta-action.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAIH,mDAAsD;AAEtD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAsB,UAAU;IAW9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,OAAsB;QAC7B,qDAAqD;QACrD,wDAAwD;QACxD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACzB,CAAC;IASD;;OAEG;IACH,oBAAoB,CAAU;IAE9B;;OAEG;IACH,iBAAiB,CAAU;IAE3B;;OAEG;IACH,KAAK,CAAU;IAEf;;;OAGG;IACH,QAAQ,CAAU;IAElB;;OAEG;IACH;QACE,iEAAiE;IACnE,CAAC;IAUD;;;;;;;;;;;;;;;;OAgBG;IACO,gBAAgB;QACxB,IAAI,IAAI,CAAC,EAAE,EAAE,CAAC;YACZ,mCAAmB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;CACF;AA7FD,gCA6FC"}

package/dist/actions/meta-registry.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Meta-Command Registry
+ *
+ * Centralized registry for tracking which commands are meta-commands.
+ * Meta-commands don't increment turns, trigger NPCs, or get recorded in history.
+ */
+/**
+ * Registry for meta-commands
+ *
+ * Maintains a list of action IDs that should be treated as meta-commands.
+ * This includes both standard system commands (SAVE, RESTORE, etc.) and
+ * custom meta-commands (debug commands, author commands, etc.).
+ */
+export declare class MetaCommandRegistry {
+    /**
+     * Set of registered meta-command IDs
+     * Pre-populated with standard IF meta-commands
+     */
+    private static metaCommands;
+    /**
+     * Register an action ID as a meta-command
+     *
+     * @param actionId The action ID to register
+     * @example
+     * ```typescript
+     * MetaCommandRegistry.register('my_debug_command');
+     * ```
+     */
+    static register(actionId: string): void;
+    /**
+     * Unregister an action ID from meta-commands
+     * Useful for testing or dynamic configuration
+     *
+     * @param actionId The action ID to unregister
+     * @returns true if the command was registered and is now removed
+     */
+    static unregister(actionId: string): boolean;
+    /**
+     * Check if an action ID is registered as a meta-command
+     *
+     * @param actionId The action ID to check
+     * @returns true if this is a meta-command
+     * @example
+     * ```typescript
+     * if (!MetaCommandRegistry.isMeta(result.actionId)) {
+     *   // Increment turn counter
+     *   this.updateContext(result);
+     * }
+     * ```
+     */
+    static isMeta(actionId: string): boolean;
+    /**
+     * Get all registered meta-command IDs
+     * Useful for debugging and documentation
+     *
+     * @returns Array of all registered meta-command IDs
+     */
+    static getAll(): string[];
+    /**
+     * Clear all registered meta-commands
+     * Useful for testing - resets to default state
+     */
+    static clear(): void;
+    /**
+     * Reset to default meta-commands
+     * Removes any custom registrations and restores defaults
+     */
+    static reset(): void;
+    /**
+     * Get the count of registered meta-commands
+     *
+     * @returns Number of registered meta-commands
+     */
+    static count(): number;
+    /**
+     * Check if registry has any custom (non-default) meta-commands
+     *
+     * @returns true if any non-default commands are registered
+     */
+    static hasCustomCommands(): boolean;
+    /**
+     * Common verb strings for non-undoable commands.
+     *
+     * Used for early detection before parsing (when action ID is not yet available).
+     * Includes both meta-commands and info commands that don't change game state.
+     *
+     * @internal Used by game engine for undo snapshot decisions
+     */
+    private static nonUndoableVerbs;
+    /**
+     * Check if a raw input string is a non-undoable command.
+     *
+     * Used for early detection before parsing when we don't have an action ID yet.
+     * This covers:
+     * - Meta-commands (save, restore, quit, restart, undo, etc.)
+     * - Info commands (look, examine, inventory)
+     *
+     * @param input Raw command input string
+     * @returns true if this command should not create an undo snapshot
+     *
+     * @example
+     * ```typescript
+     * if (!MetaCommandRegistry.isNonUndoable(input)) {
+     *   createUndoSnapshot();
+     * }
+     * ```
+     */
+    static isNonUndoable(input: string): boolean;
+}
+//# sourceMappingURL=meta-registry.d.ts.map

package/dist/actions/meta-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-registry.d.ts","sourceRoot":"","sources":["../../src/actions/meta-registry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;;GAMG;AACH,qBAAa,mBAAmB;IAC9B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY,CAgCxB;IAEH;;;;;;;;OAQG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAQvC;;;;;;OAMG;IACH,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAI5C;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKxC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,IAAI,MAAM,EAAE;IAIzB;;;OAGG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAMpB;;;OAGG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAuBpB;;;;OAIG;IACH,MAAM,CAAC,KAAK,IAAI,MAAM;IAItB;;;;OAIG;IACH,MAAM,CAAC,iBAAiB,IAAI,OAAO;IAgBnC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB,CAU5B;IAEH;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;CAK7C"}

package/dist/actions/meta-registry.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * Meta-Command Registry
+ *
+ * Centralized registry for tracking which commands are meta-commands.
+ * Meta-commands don't increment turns, trigger NPCs, or get recorded in history.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetaCommandRegistry = void 0;
+/**
+ * Registry for meta-commands
+ *
+ * Maintains a list of action IDs that should be treated as meta-commands.
+ * This includes both standard system commands (SAVE, RESTORE, etc.) and
+ * custom meta-commands (debug commands, author commands, etc.).
+ */
+class MetaCommandRegistry {
+    /**
+     * Set of registered meta-command IDs
+     * Pre-populated with standard IF meta-commands
+     */
+    static metaCommands = new Set([
+        // System commands (using IF action IDs)
+        'if.action.saving', // SAVE
+        'if.action.restoring', // RESTORE / LOAD
+        'if.action.quitting', // QUIT / Q
+        'if.action.restarting', // RESTART
+        // Information commands
+        'if.action.scoring', // SCORE / STATUS
+        'if.action.version', // VERSION
+        'if.action.about', // ABOUT
+        'if.action.help', // HELP
+        // Transcript commands
+        'transcript', // TRANSCRIPT ON/OFF
+        'transcript_on', // TRANSCRIPT ON
+        'transcript_off', // TRANSCRIPT OFF
+        // Undo system
+        'if.action.again', // AGAIN (repeat last command)
+        'if.action.undoing', // UNDO (action ID)
+        'undo', // UNDO (grammar pattern)
+        // Preference commands
+        'verbose', // VERBOSE mode
+        'brief', // BRIEF mode
+        'superbrief', // SUPERBRIEF mode
+        'notify', // NOTIFY ON/OFF
+        // Debug/Author commands (will be auto-registered by MetaAction)
+        // Listed here for documentation
+        // 'author.trace',
+    ]);
+    /**
+     * Register an action ID as a meta-command
+     *
+     * @param actionId The action ID to register
+     * @example
+     * ```typescript
+     * MetaCommandRegistry.register('my_debug_command');
+     * ```
+     */
+    static register(actionId) {
+        if (!actionId) {
+            console.warn('MetaCommandRegistry: Attempted to register empty action ID');
+            return;
+        }
+        this.metaCommands.add(actionId);
+    }
+    /**
+     * Unregister an action ID from meta-commands
+     * Useful for testing or dynamic configuration
+     *
+     * @param actionId The action ID to unregister
+     * @returns true if the command was registered and is now removed
+     */
+    static unregister(actionId) {
+        return this.metaCommands.delete(actionId);
+    }
+    /**
+     * Check if an action ID is registered as a meta-command
+     *
+     * @param actionId The action ID to check
+     * @returns true if this is a meta-command
+     * @example
+     * ```typescript
+     * if (!MetaCommandRegistry.isMeta(result.actionId)) {
+     *   // Increment turn counter
+     *   this.updateContext(result);
+     * }
+     * ```
+     */
+    static isMeta(actionId) {
+        if (!actionId)
+            return false;
+        return this.metaCommands.has(actionId);
+    }
+    /**
+     * Get all registered meta-command IDs
+     * Useful for debugging and documentation
+     *
+     * @returns Array of all registered meta-command IDs
+     */
+    static getAll() {
+        return Array.from(this.metaCommands).sort();
+    }
+    /**
+     * Clear all registered meta-commands
+     * Useful for testing - resets to default state
+     */
+    static clear() {
+        this.metaCommands.clear();
+        // Re-add standard commands
+        this.reset();
+    }
+    /**
+     * Reset to default meta-commands
+     * Removes any custom registrations and restores defaults
+     */
+    static reset() {
+        this.metaCommands = new Set([
+            'if.action.saving',
+            'if.action.restoring',
+            'if.action.quitting',
+            'if.action.restarting',
+            'if.action.undoing',
+            'if.action.scoring',
+            'if.action.version',
+            'if.action.about',
+            'if.action.help',
+            'if.action.again',
+            'transcript',
+            'transcript_on',
+            'transcript_off',
+            'undo',
+            'verbose',
+            'brief',
+            'superbrief',
+            'notify'
+        ]);
+    }
+    /**
+     * Get the count of registered meta-commands
+     *
+     * @returns Number of registered meta-commands
+     */
+    static count() {
+        return this.metaCommands.size;
+    }
+    /**
+     * Check if registry has any custom (non-default) meta-commands
+     *
+     * @returns true if any non-default commands are registered
+     */
+    static hasCustomCommands() {
+        const defaults = new Set([
+            'if.action.saving', 'if.action.restoring', 'if.action.quitting', 'if.action.restarting',
+            'if.action.undoing', 'if.action.scoring', 'if.action.version', 'if.action.about', 'if.action.help',
+            'if.action.again', 'transcript', 'transcript_on', 'transcript_off',
+            'undo', 'verbose', 'brief', 'superbrief', 'notify'
+        ]);
+        for (const cmd of this.metaCommands) {
+            if (!defaults.has(cmd)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Common verb strings for non-undoable commands.
+     *
+     * Used for early detection before parsing (when action ID is not yet available).
+     * Includes both meta-commands and info commands that don't change game state.
+     *
+     * @internal Used by game engine for undo snapshot decisions
+     */
+    static nonUndoableVerbs = new Set([
+        // Meta-commands (match MetaCommandRegistry)
+        'undo', 'save', 'restore', 'restart', 'quit',
+        'score', 'version', 'about', 'help',
+        'verbose', 'brief', 'superbrief', 'notify',
+        'again', 'g',
+        // Info commands (don't change game state)
+        'look', 'l',
+        'examine', 'x',
+        'inventory', 'i'
+    ]);
+    /**
+     * Check if a raw input string is a non-undoable command.
+     *
+     * Used for early detection before parsing when we don't have an action ID yet.
+     * This covers:
+     * - Meta-commands (save, restore, quit, restart, undo, etc.)
+     * - Info commands (look, examine, inventory)
+     *
+     * @param input Raw command input string
+     * @returns true if this command should not create an undo snapshot
+     *
+     * @example
+     * ```typescript
+     * if (!MetaCommandRegistry.isNonUndoable(input)) {
+     *   createUndoSnapshot();
+     * }
+     * ```
+     */
+    static isNonUndoable(input) {
+        const normalized = input.trim().toLowerCase();
+        const firstWord = normalized.split(/\s+/)[0];
+        return this.nonUndoableVerbs.has(firstWord);
+    }
+}
+exports.MetaCommandRegistry = MetaCommandRegistry;
+//# sourceMappingURL=meta-registry.js.map

package/dist/actions/meta-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-registry.js","sourceRoot":"","sources":["../../src/actions/meta-registry.ts"],"names":[],"mappings":"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"}