@sharpee/world-model 0.9.60-beta → 0.9.61-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Cornelson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist-npm/capabilities/action-interceptor.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Action Interceptor interface (ADR-118)
+ *
+ * Interceptors allow entities to hook into stdlib action phases
+ * without replacing standard logic. This is the "Before/After" pattern
+ * from Inform 6/7, complementing the full delegation pattern in
+ * capability behaviors.
+ *
+ * Key difference from CapabilityBehavior:
+ * - CapabilityBehavior: Full delegation, trait owns ALL logic (LOWER, RAISE)
+ * - ActionInterceptor: Hooks into phases, action owns core logic (ENTER, PUT)
+ */
+import { IFEntity } from '../entities';
+import { WorldModel } from '../world';
+import { CapabilityEffect } from './types';
+/**
+ * Shared data object for passing data between interceptor phases.
+ * Mirrors CapabilitySharedData pattern from capability-behavior.ts.
+ *
+ * Interceptors can store data here during earlier phases (e.g., postValidate)
+ * and access it in later phases (e.g., postExecute, postReport).
+ */
+export type InterceptorSharedData = Record<string, unknown>;
+/**
+ * Result from interceptor validation hooks.
+ * Returning null means "continue with standard logic".
+ * Returning a result blocks or modifies the action.
+ */
+export interface InterceptorResult {
+    /** Whether the action can proceed */
+    valid: boolean;
+    /** Error code if validation failed (for message lookup) */
+    error?: string;
+    /** Additional context for error messages */
+    params?: Record<string, unknown>;
+}
+/**
+ * Action interceptor interface.
+ *
+ * Interceptors hook into stdlib action phases to customize behavior
+ * without reimplementing standard logic. All hooks are optional.
+ *
+ * Phase order:
+ * 1. preValidate - Before standard validation
+ * 2. (standard validation runs)
+ * 3. postValidate - After standard validation passes
+ * 4. (standard execute runs)
+ * 5. postExecute - After standard execution
+ * 6. (standard report runs)
+ * 7. postReport - Additional effects after standard report
+ *
+ * If validation fails at any point:
+ * - onBlocked - Called instead of execute/report phases
+ *
+ * @example
+ * ```typescript
+ * // Boat puncture interceptor - checks for sharp objects when entering
+ * const InflatableEnteringInterceptor: ActionInterceptor = {
+ *   postValidate(entity, world, actorId, sharedData) {
+ *     const inventory = world.getContents(actorId);
+ *     const sharpObject = inventory.find(item => item.puncturesBoat);
+ *     if (sharpObject) {
+ *       sharedData.willPuncture = true;
+ *       sharedData.punctureItem = sharpObject.name;
+ *     }
+ *     return null; // Allow entering to proceed
+ *   },
+ *
+ *   postExecute(entity, world, actorId, sharedData) {
+ *     if (!sharedData.willPuncture) return;
+ *     // Deflate the boat, eject player
+ *     const trait = entity.get(InflatableTrait);
+ *     trait.isInflated = false;
+ *     world.moveEntity(actorId, world.getLocation(entity.id));
+ *   },
+ *
+ *   postReport(entity, world, actorId, sharedData) {
+ *     if (!sharedData.willPuncture) return [];
+ *     return [createEffect('dungeo.boat.punctured', { item: sharedData.punctureItem })];
+ *   }
+ * };
+ * ```
+ */
+export interface ActionInterceptor {
+    /**
+     * Called BEFORE standard validation.
+     *
+     * Use this to block actions early based on entity-specific conditions.
+     * Return an InterceptorResult to block the action.
+     * Return null to continue with standard validation.
+     *
+     * @example
+     * // Troll blocks entering the Troll Room
+     * preValidate(entity, world, actorId, sharedData) {
+     *   if (trollIsAlive(world)) {
+     *     return { valid: false, error: 'dungeo.troll.blocks_path' };
+     *   }
+     *   return null;
+     * }
+     */
+    preValidate?(entity: IFEntity, world: WorldModel, actorId: string, sharedData: InterceptorSharedData): InterceptorResult | null;
+    /**
+     * Called AFTER standard validation passes.
+     *
+     * Use this to add entity-specific conditions that should block
+     * an otherwise valid action, or to set up data for postExecute.
+     * Return an InterceptorResult to block the action.
+     * Return null to continue with execution.
+     *
+     * @example
+     * // Check if player is carrying something that will puncture the boat
+     * postValidate(entity, world, actorId, sharedData) {
+     *   const sharp = findSharpObject(world, actorId);
+     *   if (sharp) {
+     *     sharedData.willPuncture = true;
+     *     sharedData.punctureItem = sharp.name;
+     *   }
+     *   return null; // Still allow entering
+     * }
+     */
+    postValidate?(entity: IFEntity, world: WorldModel, actorId: string, sharedData: InterceptorSharedData): InterceptorResult | null;
+    /**
+     * Called AFTER standard execution completes.
+     *
+     * Use this to perform additional mutations based on the action.
+     * Cannot prevent the action (use postValidate for that).
+     * Access data stored in sharedData during validation phases.
+     *
+     * @example
+     * // Glacier melts when torch is thrown at it
+     * postExecute(entity, world, actorId, sharedData) {
+     *   if (!sharedData.willMelt) return;
+     *   meltGlacier(world, entity.id);
+     *   openPassage(world, 'glacier-passage');
+     * }
+     */
+    postExecute?(entity: IFEntity, world: WorldModel, actorId: string, sharedData: InterceptorSharedData): void;
+    /**
+     * Called AFTER standard report.
+     *
+     * Return additional effects to emit after the standard effects.
+     * Return empty array if no additional effects needed.
+     *
+     * @example
+     * // Add glacier melting message
+     * postReport(entity, world, actorId, sharedData) {
+     *   if (!sharedData.melted) return [];
+     *   return [createEffect('dungeo.glacier.melted', { messageId: 'dungeo.glacier.melts' })];
+     * }
+     */
+    postReport?(entity: IFEntity, world: WorldModel, actorId: string, sharedData: InterceptorSharedData): CapabilityEffect[];
+    /**
+     * Called when action is blocked (validation failed).
+     *
+     * Use this to provide custom blocked handling for this entity.
+     * Return effects to emit, or null to use standard blocked handling.
+     *
+     * @example
+     * // Custom message when troll blocks entry
+     * onBlocked(entity, world, actorId, error, sharedData) {
+     *   if (error === 'dungeo.troll.blocks_path') {
+     *     return [createEffect('game.message', { messageId: 'dungeo.troll.snarls' })];
+     *   }
+     *   return null; // Use standard blocked handling
+     * }
+     */
+    onBlocked?(entity: IFEntity, world: WorldModel, actorId: string, error: string, sharedData: InterceptorSharedData): CapabilityEffect[] | null;
+}
+//# sourceMappingURL=action-interceptor.d.ts.map

package/dist-npm/capabilities/action-interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-interceptor.d.ts","sourceRoot":"","sources":["../../src/capabilities/action-interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,CACV,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,qBAAqB,GAChC,iBAAiB,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,CACX,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,qBAAqB,GAChC,iBAAiB,GAAG,IAAI,CAAC;IAE5B;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,CACV,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,qBAAqB,GAChC,IAAI,CAAC;IAER;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,CACT,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,qBAAqB,GAChC,gBAAgB,EAAE,CAAC;IAEtB;;;;;;;;;;;;;;OAcG;IACH,SAAS,CAAC,CACR,MAAM,EAAE,QAAQ,EAChB,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,qBAAqB,GAChC,gBAAgB,EAAE,GAAG,IAAI,CAAC;CAC9B"}

package/dist-npm/capabilities/action-interceptor.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Action Interceptor interface (ADR-118)
+ *
+ * Interceptors allow entities to hook into stdlib action phases
+ * without replacing standard logic. This is the "Before/After" pattern
+ * from Inform 6/7, complementing the full delegation pattern in
+ * capability behaviors.
+ *
+ * Key difference from CapabilityBehavior:
+ * - CapabilityBehavior: Full delegation, trait owns ALL logic (LOWER, RAISE)
+ * - ActionInterceptor: Hooks into phases, action owns core logic (ENTER, PUT)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=action-interceptor.js.map

package/dist-npm/capabilities/action-interceptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-interceptor.js","sourceRoot":"","sources":["../../src/capabilities/action-interceptor.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

package/{dist → dist-npm}/capabilities/index.d.ts

@@ -10,4 +10,7 @@ export { TraitBehaviorBinding, BehaviorRegistrationOptions, registerCapabilityBe
 export { CapabilityResolution, CapabilityMode, CapabilityConfig, defineCapabilityDefaults, getCapabilityConfig, hasCapabilityDefaults, clearCapabilityDefaults, getAllCapabilityDefaults } from './capability-defaults';
 export { findTraitWithCapability, hasCapability, getEntityCapabilities, traitHasCapability, getCapableTraits } from './capability-helpers';
 export { EntityBuilder, buildEntity } from './entity-builder';
+export { ActionInterceptor, InterceptorSharedData, InterceptorResult } from './action-interceptor';
+export { TraitInterceptorBinding, InterceptorRegistrationOptions, InterceptorLookupResult, registerActionInterceptor, getInterceptorForAction, getInterceptorBinding, hasActionInterceptor, unregisterActionInterceptor, clearInterceptorRegistry, getAllInterceptorBindings } from './interceptor-registry';
+export { findTraitWithInterceptor, hasInterceptor, getEntityInterceptors, traitHasInterceptor, getInterceptorTraits } from './interceptor-helpers';
 //# sourceMappingURL=index.d.ts.map

package/{dist → dist-npm}/capabilities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,YAAY,EACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,aAAa,EACb,WAAW,EACZ,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,0BAA0B,EAC1B,gBAAgB,EAChB,YAAY,EACb,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGjF,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,0BAA0B,EAC1B,wBAAwB,EACxB,kBAAkB,EAClB,qBAAqB,EACrB,4BAA4B,EAC5B,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,aAAa,EACb,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAW1B,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,uBAAuB,EACvB,yBAAyB,EACzB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EAC1B,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,wBAAwB,EACxB,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,uBAAuB,CAAC"}

package/{dist → dist-npm}/capabilities/index.js

@@ -6,7 +6,7 @@
  * (action IDs they respond to) and behaviors implement the logic.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildEntity = exports.EntityBuilder = exports.getCapableTraits = exports.traitHasCapability = exports.getEntityCapabilities = exports.hasCapability = exports.findTraitWithCapability = exports.getAllCapabilityDefaults = exports.clearCapabilityDefaults = exports.hasCapabilityDefaults = exports.getCapabilityConfig = exports.defineCapabilityDefaults = exports.getAllCapabilityBindings = exports.clearCapabilityRegistry = exports.unregisterCapabilityBehavior = exports.hasCapabilityBehavior = exports.getBehaviorBinding = exports.getBehaviorForCapability = exports.registerCapabilityBehavior = exports.createEffect = void 0;
+exports.getInterceptorTraits = exports.traitHasInterceptor = exports.getEntityInterceptors = exports.hasInterceptor = exports.findTraitWithInterceptor = exports.getAllInterceptorBindings = exports.clearInterceptorRegistry = exports.unregisterActionInterceptor = exports.hasActionInterceptor = exports.getInterceptorBinding = exports.getInterceptorForAction = exports.registerActionInterceptor = exports.buildEntity = exports.EntityBuilder = exports.getCapableTraits = exports.traitHasCapability = exports.getEntityCapabilities = exports.hasCapability = exports.findTraitWithCapability = exports.getAllCapabilityDefaults = exports.clearCapabilityDefaults = exports.hasCapabilityDefaults = exports.getCapabilityConfig = exports.defineCapabilityDefaults = exports.getAllCapabilityBindings = exports.clearCapabilityRegistry = exports.unregisterCapabilityBehavior = exports.hasCapabilityBehavior = exports.getBehaviorBinding = exports.getBehaviorForCapability = exports.registerCapabilityBehavior = exports.createEffect = void 0;
 // Types
 var types_1 = require("./types");
 Object.defineProperty(exports, "createEffect", { enumerable: true, get: function () { return types_1.createEffect; } });
@@ -37,4 +37,20 @@ Object.defineProperty(exports, "getCapableTraits", { enumerable: true, get: func
 var entity_builder_1 = require("./entity-builder");
 Object.defineProperty(exports, "EntityBuilder", { enumerable: true, get: function () { return entity_builder_1.EntityBuilder; } });
 Object.defineProperty(exports, "buildEntity", { enumerable: true, get: function () { return entity_builder_1.buildEntity; } });
+// Interceptor registry
+var interceptor_registry_1 = require("./interceptor-registry");
+Object.defineProperty(exports, "registerActionInterceptor", { enumerable: true, get: function () { return interceptor_registry_1.registerActionInterceptor; } });
+Object.defineProperty(exports, "getInterceptorForAction", { enumerable: true, get: function () { return interceptor_registry_1.getInterceptorForAction; } });
+Object.defineProperty(exports, "getInterceptorBinding", { enumerable: true, get: function () { return interceptor_registry_1.getInterceptorBinding; } });
+Object.defineProperty(exports, "hasActionInterceptor", { enumerable: true, get: function () { return interceptor_registry_1.hasActionInterceptor; } });
+Object.defineProperty(exports, "unregisterActionInterceptor", { enumerable: true, get: function () { return interceptor_registry_1.unregisterActionInterceptor; } });
+Object.defineProperty(exports, "clearInterceptorRegistry", { enumerable: true, get: function () { return interceptor_registry_1.clearInterceptorRegistry; } });
+Object.defineProperty(exports, "getAllInterceptorBindings", { enumerable: true, get: function () { return interceptor_registry_1.getAllInterceptorBindings; } });
+// Interceptor helpers
+var interceptor_helpers_1 = require("./interceptor-helpers");
+Object.defineProperty(exports, "findTraitWithInterceptor", { enumerable: true, get: function () { return interceptor_helpers_1.findTraitWithInterceptor; } });
+Object.defineProperty(exports, "hasInterceptor", { enumerable: true, get: function () { return interceptor_helpers_1.hasInterceptor; } });
+Object.defineProperty(exports, "getEntityInterceptors", { enumerable: true, get: function () { return interceptor_helpers_1.getEntityInterceptors; } });
+Object.defineProperty(exports, "traitHasInterceptor", { enumerable: true, get: function () { return interceptor_helpers_1.traitHasInterceptor; } });
+Object.defineProperty(exports, "getInterceptorTraits", { enumerable: true, get: function () { return interceptor_helpers_1.getInterceptorTraits; } });
 //# sourceMappingURL=index.js.map

package/{dist → dist-npm}/capabilities/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,QAAQ;AACR,iCAIiB;AADf,qGAAA,YAAY,OAAA;AAMd,WAAW;AACX,6DAU+B;AAP7B,iIAAA,0BAA0B,OAAA;AAC1B,+HAAA,wBAAwB,OAAA;AACxB,yHAAA,kBAAkB,OAAA;AAClB,4HAAA,qBAAqB,OAAA;AACrB,mIAAA,4BAA4B,OAAA;AAC5B,8HAAA,uBAAuB,OAAA;AACvB,+HAAA,wBAAwB,OAAA;AAG1B,6BAA6B;AAC7B,6DAS+B;AAL7B,+HAAA,wBAAwB,OAAA;AACxB,0HAAA,mBAAmB,OAAA;AACnB,4HAAA,qBAAqB,OAAA;AACrB,8HAAA,uBAAuB,OAAA;AACvB,+HAAA,wBAAwB,OAAA;AAG1B,UAAU;AACV,2DAM8B;AAL5B,6HAAA,uBAAuB,OAAA;AACvB,mHAAA,aAAa,OAAA;AACb,2HAAA,qBAAqB,OAAA;AACrB,wHAAA,kBAAkB,OAAA;AAClB,sHAAA,gBAAgB,OAAA;AAGlB,iBAAiB;AACjB,mDAG0B;AAFxB,+GAAA,aAAa,OAAA;AACb,6GAAA,WAAW,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,QAAQ;AACR,iCAIiB;AADf,qGAAA,YAAY,OAAA;AAMd,WAAW;AACX,6DAU+B;AAP7B,iIAAA,0BAA0B,OAAA;AAC1B,+HAAA,wBAAwB,OAAA;AACxB,yHAAA,kBAAkB,OAAA;AAClB,4HAAA,qBAAqB,OAAA;AACrB,mIAAA,4BAA4B,OAAA;AAC5B,8HAAA,uBAAuB,OAAA;AACvB,+HAAA,wBAAwB,OAAA;AAG1B,6BAA6B;AAC7B,6DAS+B;AAL7B,+HAAA,wBAAwB,OAAA;AACxB,0HAAA,mBAAmB,OAAA;AACnB,4HAAA,qBAAqB,OAAA;AACrB,8HAAA,uBAAuB,OAAA;AACvB,+HAAA,wBAAwB,OAAA;AAG1B,UAAU;AACV,2DAM8B;AAL5B,6HAAA,uBAAuB,OAAA;AACvB,mHAAA,aAAa,OAAA;AACb,2HAAA,qBAAqB,OAAA;AACrB,wHAAA,kBAAkB,OAAA;AAClB,sHAAA,gBAAgB,OAAA;AAGlB,iBAAiB;AACjB,mDAG0B;AAFxB,+GAAA,aAAa,OAAA;AACb,6GAAA,WAAW,OAAA;AAkBb,uBAAuB;AACvB,+DAWgC;AAP9B,iIAAA,yBAAyB,OAAA;AACzB,+HAAA,uBAAuB,OAAA;AACvB,6HAAA,qBAAqB,OAAA;AACrB,4HAAA,oBAAoB,OAAA;AACpB,mIAAA,2BAA2B,OAAA;AAC3B,gIAAA,wBAAwB,OAAA;AACxB,iIAAA,yBAAyB,OAAA;AAG3B,sBAAsB;AACtB,6DAM+B;AAL7B,+HAAA,wBAAwB,OAAA;AACxB,qHAAA,cAAc,OAAA;AACd,4HAAA,qBAAqB,OAAA;AACrB,0HAAA,mBAAmB,OAAA;AACnB,2HAAA,oBAAoB,OAAA"}

package/dist-npm/capabilities/interceptor-helpers.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Interceptor Helpers (ADR-118)
+ *
+ * Helper functions for working with trait interceptors.
+ * Mirrors capability-helpers.ts pattern but for interceptors.
+ */
+import { ITrait } from '../traits/trait';
+import { IFEntity } from '../entities';
+/**
+ * Find a trait on the entity that has an interceptor registered for the given action.
+ *
+ * Note: This checks both the static `interceptors` declaration on the trait class
+ * AND the registry. Use this when you need the trait instance.
+ *
+ * @param entity - The entity to search
+ * @param actionId - The action ID to find
+ * @returns The trait that has an interceptor registered, or undefined
+ *
+ * @example
+ * ```typescript
+ * const trait = findTraitWithInterceptor(boat, 'if.action.entering');
+ * if (trait) {
+ *   // Entity has an interceptor for entering
+ * }
+ * ```
+ */
+export declare function findTraitWithInterceptor(entity: IFEntity, actionId: string): ITrait | undefined;
+/**
+ * Check if an entity has any trait declaring an interceptor for an action.
+ *
+ * @param entity - The entity to check
+ * @param actionId - The action ID to check for
+ * @returns True if entity has a trait with this interceptor
+ *
+ * @example
+ * ```typescript
+ * if (hasInterceptor(entity, 'if.action.entering')) {
+ *   // Entity can intercept entering actions
+ * }
+ * ```
+ */
+export declare function hasInterceptor(entity: IFEntity, actionId: string): boolean;
+/**
+ * Get all interceptor action IDs declared by an entity's traits.
+ *
+ * @param entity - The entity to inspect
+ * @returns Array of action IDs the entity intercepts
+ */
+export declare function getEntityInterceptors(entity: IFEntity): string[];
+/**
+ * Type guard to check if a trait declares a specific interceptor.
+ *
+ * @param trait - The trait to check
+ * @param actionId - The action ID to check for
+ * @param traitType - Optional: specific trait class to narrow to
+ * @returns True if trait has the interceptor (and is of specified type)
+ *
+ * @example
+ * ```typescript
+ * if (traitHasInterceptor(trait, 'if.action.entering', InflatableTrait)) {
+ *   // trait is narrowed to InflatableTrait
+ *   console.log(trait.isInflated);
+ * }
+ * ```
+ */
+export declare function traitHasInterceptor<T extends ITrait>(trait: ITrait, actionId: string, traitType?: new (...args: unknown[]) => T): trait is T;
+/**
+ * Find all traits on an entity that have interceptors.
+ *
+ * @param entity - The entity to inspect
+ * @returns Array of traits that declare at least one interceptor
+ */
+export declare function getInterceptorTraits(entity: IFEntity): ITrait[];
+//# sourceMappingURL=interceptor-helpers.d.ts.map

package/dist-npm/capabilities/interceptor-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor-helpers.d.ts","sourceRoot":"","sources":["../../src/capabilities/interceptor-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAqB,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,QAAQ,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CASpB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAE1E;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,CAWhE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GACxC,KAAK,IAAI,CAAC,CAQZ;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,EAAE,CAK/D"}

package/dist-npm/capabilities/interceptor-helpers.js

@@ -0,0 +1,111 @@
+"use strict";
+/**
+ * Interceptor Helpers (ADR-118)
+ *
+ * Helper functions for working with trait interceptors.
+ * Mirrors capability-helpers.ts pattern but for interceptors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findTraitWithInterceptor = findTraitWithInterceptor;
+exports.hasInterceptor = hasInterceptor;
+exports.getEntityInterceptors = getEntityInterceptors;
+exports.traitHasInterceptor = traitHasInterceptor;
+exports.getInterceptorTraits = getInterceptorTraits;
+/**
+ * Find a trait on the entity that has an interceptor registered for the given action.
+ *
+ * Note: This checks both the static `interceptors` declaration on the trait class
+ * AND the registry. Use this when you need the trait instance.
+ *
+ * @param entity - The entity to search
+ * @param actionId - The action ID to find
+ * @returns The trait that has an interceptor registered, or undefined
+ *
+ * @example
+ * ```typescript
+ * const trait = findTraitWithInterceptor(boat, 'if.action.entering');
+ * if (trait) {
+ *   // Entity has an interceptor for entering
+ * }
+ * ```
+ */
+function findTraitWithInterceptor(entity, actionId) {
+    for (const trait of entity.traits.values()) {
+        // First check static declaration (if available)
+        const traitClass = trait.constructor;
+        if (traitClass.interceptors?.includes(actionId)) {
+            return trait;
+        }
+    }
+    return undefined;
+}
+/**
+ * Check if an entity has any trait declaring an interceptor for an action.
+ *
+ * @param entity - The entity to check
+ * @param actionId - The action ID to check for
+ * @returns True if entity has a trait with this interceptor
+ *
+ * @example
+ * ```typescript
+ * if (hasInterceptor(entity, 'if.action.entering')) {
+ *   // Entity can intercept entering actions
+ * }
+ * ```
+ */
+function hasInterceptor(entity, actionId) {
+    return findTraitWithInterceptor(entity, actionId) !== undefined;
+}
+/**
+ * Get all interceptor action IDs declared by an entity's traits.
+ *
+ * @param entity - The entity to inspect
+ * @returns Array of action IDs the entity intercepts
+ */
+function getEntityInterceptors(entity) {
+    const interceptors = [];
+    for (const trait of entity.traits.values()) {
+        const traitClass = trait.constructor;
+        if (traitClass.interceptors) {
+            interceptors.push(...traitClass.interceptors);
+        }
+    }
+    return interceptors;
+}
+/**
+ * Type guard to check if a trait declares a specific interceptor.
+ *
+ * @param trait - The trait to check
+ * @param actionId - The action ID to check for
+ * @param traitType - Optional: specific trait class to narrow to
+ * @returns True if trait has the interceptor (and is of specified type)
+ *
+ * @example
+ * ```typescript
+ * if (traitHasInterceptor(trait, 'if.action.entering', InflatableTrait)) {
+ *   // trait is narrowed to InflatableTrait
+ *   console.log(trait.isInflated);
+ * }
+ * ```
+ */
+function traitHasInterceptor(trait, actionId, traitType) {
+    const traitClass = trait.constructor;
+    const hasAction = traitClass.interceptors?.includes(actionId) ?? false;
+    if (traitType) {
+        return hasAction && trait instanceof traitType;
+    }
+    return hasAction;
+}
+/**
+ * Find all traits on an entity that have interceptors.
+ *
+ * @param entity - The entity to inspect
+ * @returns Array of traits that declare at least one interceptor
+ */
+function getInterceptorTraits(entity) {
+    return Array.from(entity.traits.values()).filter(trait => {
+        const traitClass = trait.constructor;
+        return traitClass.interceptors && traitClass.interceptors.length > 0;
+    });
+}
+//# sourceMappingURL=interceptor-helpers.js.map

package/dist-npm/capabilities/interceptor-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor-helpers.js","sourceRoot":"","sources":["../../src/capabilities/interceptor-helpers.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;AAuBH,4DAYC;AAgBD,wCAEC;AAQD,sDAWC;AAkBD,kDAYC;AAQD,oDAKC;AA9GD;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,wBAAwB,CACtC,MAAgB,EAChB,QAAgB;IAEhB,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QAC3C,gDAAgD;QAChD,MAAM,UAAU,GAAG,KAAK,CAAC,WAAgC,CAAC;QAC1D,IAAI,UAAU,CAAC,YAAY,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAgB,cAAc,CAAC,MAAgB,EAAE,QAAgB;IAC/D,OAAO,wBAAwB,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,SAAS,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CAAC,MAAgB;IACpD,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QAC3C,MAAM,UAAU,GAAG,KAAK,CAAC,WAAgC,CAAC;QAC1D,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;YAC5B,YAAY,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IAED,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,mBAAmB,CACjC,KAAa,EACb,QAAgB,EAChB,SAAyC;IAEzC,MAAM,UAAU,GAAG,KAAK,CAAC,WAAgC,CAAC;IAC1D,MAAM,SAAS,GAAG,UAAU,CAAC,YAAY,EAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC;IAEvE,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,IAAI,KAAK,YAAY,SAAS,CAAC;IACjD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,oBAAoB,CAAC,MAAgB;IACnD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;QACvD,MAAM,UAAU,GAAG,KAAK,CAAC,WAAgC,CAAC;QAC1D,OAAO,UAAU,CAAC,YAAY,IAAI,UAAU,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist-npm/capabilities/interceptor-registry.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Interceptor Registry (ADR-118)
+ *
+ * Registry for trait-interceptor bindings. Stories register interceptors
+ * for their traits, and stdlib actions look them up at runtime.
+ *
+ * Mirrors capability-registry.ts pattern but for interceptors instead
+ * of full-delegation behaviors.
+ */
+import { ITrait } from '../traits/trait';
+import { ActionInterceptor } from './action-interceptor';
+/**
+ * Options for registering an action interceptor.
+ */
+export interface InterceptorRegistrationOptions {
+    /** Priority for resolution (higher = checked first). Default: 0 */
+    priority?: number;
+}
+/**
+ * Binding between a trait type, action, and interceptor.
+ */
+export interface TraitInterceptorBinding {
+    /** Trait type identifier */
+    traitType: string;
+    /** Action ID this interceptor handles */
+    actionId: string;
+    /** The interceptor that handles this trait+action */
+    interceptor: ActionInterceptor;
+    /** Priority for resolution (higher = checked first) */
+    priority: number;
+}
+/**
+ * Register an interceptor for a trait+action combination.
+ *
+ * Stories call this to register their interceptors during initialization.
+ * Each trait+action pair can only have one interceptor registered.
+ *
+ * @param traitType - The trait type identifier (e.g., 'dungeo.trait.inflatable')
+ * @param actionId - The action ID (e.g., 'if.action.entering')
+ * @param interceptor - The interceptor implementation
+ * @param options - Optional configuration (priority)
+ *
+ * @example
+ * ```typescript
+ * // Register boat puncture interceptor
+ * registerActionInterceptor(
+ *   InflatableTrait.type,
+ *   'if.action.entering',
+ *   InflatableEnteringInterceptor
+ * );
+ *
+ * // With priority
+ * registerActionInterceptor(
+ *   TrollGuardianTrait.type,
+ *   'if.action.going',
+ *   TrollGoingInterceptor,
+ *   { priority: 100 }
+ * );
+ * ```
+ */
+export declare function registerActionInterceptor(traitType: string, actionId: string, interceptor: ActionInterceptor, options?: InterceptorRegistrationOptions): void;
+/**
+ * Result from looking up an interceptor for an entity+action.
+ */
+export interface InterceptorLookupResult {
+    /** The interceptor */
+    interceptor: ActionInterceptor;
+    /** The trait that declared this interceptor */
+    trait: ITrait;
+    /** The binding metadata */
+    binding: TraitInterceptorBinding;
+}
+/**
+ * Get interceptor for an entity and action.
+ *
+ * Finds a trait on the entity that has an interceptor registered for
+ * the given action. Looks up by trait type string in the registry.
+ *
+ * @param entity - The entity to check
+ * @param actionId - The action ID
+ * @returns The interceptor and trait, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const result = getInterceptorForAction(boat, 'if.action.entering');
+ * if (result) {
+ *   const { interceptor, trait, binding } = result;
+ *   // Call interceptor hooks during action execution
+ * }
+ * ```
+ */
+export declare function getInterceptorForAction(entity: {
+    traits: Map<string, ITrait>;
+}, actionId: string): InterceptorLookupResult | undefined;
+/**
+ * Get the interceptor binding for a trait type and action.
+ *
+ * @param traitType - The trait type identifier
+ * @param actionId - The action ID
+ * @returns The binding, or undefined if not registered
+ */
+export declare function getInterceptorBinding(traitType: string, actionId: string): TraitInterceptorBinding | undefined;
+/**
+ * Check if an interceptor is registered for a trait+action.
+ *
+ * @param traitType - The trait type identifier
+ * @param actionId - The action ID
+ */
+export declare function hasActionInterceptor(traitType: string, actionId: string): boolean;
+/**
+ * Unregister an interceptor (primarily for testing).
+ *
+ * @param traitType - The trait type identifier
+ * @param actionId - The action ID
+ */
+export declare function unregisterActionInterceptor(traitType: string, actionId: string): void;
+/**
+ * Clear all registered interceptors (for testing).
+ */
+export declare function clearInterceptorRegistry(): void;
+/**
+ * Get all registered interceptor bindings (for debugging/introspection).
+ */
+export declare function getAllInterceptorBindings(): Map<string, TraitInterceptorBinding>;
+//# sourceMappingURL=interceptor-registry.d.ts.map

package/dist-npm/capabilities/interceptor-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor-registry.d.ts","sourceRoot":"","sources":["../../src/capabilities/interceptor-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,MAAM,EAAqB,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,4BAA4B;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,WAAW,EAAE,iBAAiB,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAuCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,iBAAiB,EAC9B,OAAO,CAAC,EAAE,8BAA8B,GACvC,IAAI,CAeN;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,sBAAsB;IACtB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,EAAE,uBAAuB,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE;IAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,EACvC,QAAQ,EAAE,MAAM,GACf,uBAAuB,GAAG,SAAS,CA4BrC;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,uBAAuB,GAAG,SAAS,CAErC;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEjF;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAErF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED;;GAEG;AACH,wBAAgB,yBAAyB,IAAI,GAAG,CAAC,MAAM,EAAE,uBAAuB,CAAC,CAEhF"}