@sharpee/plugins 3.1.0 → 3.5.0

package/band-crossing.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The banded-scalar crossing engine (ADR-262).
+ *
+ * A continuous meter — score, hunger severity, madness — is a number that moves.
+ * As it moves it crosses *bands* (ranks, hunger stages) at absolute thresholds.
+ * This module is the shared machinery that detects those crossings and turns
+ * them into events, so each metering concept keeps only its bespoke Chord
+ * surface and lowers to one engine (ADR-262 D1).
+ *
+ * Two responsibilities, split into two plugin factories over one detector:
+ *
+ *  - {@link createBandDataWatcher} emits the generic **data** event
+ *    `if.event.band_crossed` carrying the whole crossed span (ADR-262 D2). It
+ *    is the always-on part — a TypeScript story reads it and renders promotions
+ *    itself; a Chord story gets it too.
+ *  - {@link createBandNarrator} emits **narration** events carrying a messageId
+ *    under the four verbosity modes (ADR-262 D3). This is the Chord render
+ *    layer; a rung with no author phrase speaks an overridable platform
+ *    fallback, and only `silent` suppresses.
+ *
+ * Both share {@link BandCrossingDetector}: rise-only (ADR-262 D5), the band is
+ * derived from the value every turn via `bandOf`, and the only persisted state
+ * is the last-announced band id, for crossing edge-detection across
+ * save/restore.
+ */
+import { type WorldModel } from '@sharpee/world-model';
+import type { TurnPlugin } from './turn-plugin.js';
+/** How a consumer narrates a crossing (ADR-262 D3). */
+export type BandAnnounceMode = 'all' | 'collapsed' | 'combined' | 'silent';
+/**
+ * A rung the engine tracks: a stable id, its absolute threshold, an optional
+ * display name (for narration params), and an optional per-band narration
+ * phrase message id (the author's `says` key, resolved to a message id).
+ */
+export interface BandRung {
+    id: string;
+    threshold: number;
+    name?: string;
+    phraseId?: string;
+}
+/** The span a value crossed on one turn (ADR-262 D2). */
+export interface BandCrossingSpan {
+    concept: string;
+    /** The band left behind (the last announced), or null from the bottom. */
+    fromId: string | null;
+    /** The band reached this turn. */
+    toId: string;
+    /** Every band entered this turn, in order — excludes `from`, includes `to`. */
+    rungsCrossed: BandRung[];
+    /** The scalar value at the crossing. */
+    value: number;
+}
+/** Payload of `if.event.band_crossed` (ADR-262 D2) — ids, never display names. */
+export interface BandCrossedData {
+    concept: string;
+    from: string | null;
+    to: string;
+    bandsCrossed: string[];
+    value: number;
+}
+/** Shared configuration for both the data watcher and the narrator. */
+export interface BandCrossingConfig {
+    /** Unique plugin id. */
+    id: string;
+    /** Run order; a crossing observes a turn others produced, so keep it low. */
+    priority: number;
+    /** The concept name carried in the data event and params. */
+    concept: string;
+    /** Gate: skip entirely when the concept is not installed (e.g. scoring off). */
+    isEnabled?: (world: WorldModel) => boolean;
+    /** Read the current scalar value from the world. */
+    value: (world: WorldModel) => number;
+    /** Read the ordered bands (ascending by threshold) from the world. */
+    bands: (world: WorldModel) => BandRung[];
+    /**
+     * Silently seed the baseline when the value is at or below this — the bottom
+     * rung is where the player *starts*, so announcing it would report a
+     * promotion no one earned (scoring's rung-at-0 case). Omit when the meter
+     * starts below every band (hunger: severity 0 is below all rungs).
+     */
+    seedAtOrBelow?: number;
+}
+/** Serialized state: the id of the band last announced. */
+export interface BandWatcherState {
+    lastAnnouncedId: string | null;
+}
+/**
+ * A watcher that emits the generic `if.event.band_crossed` data event on a rise
+ * (ADR-262 D2). One event per turn, carrying the whole crossed span, no
+ * messageId. `dataEventId` is passed in (typically `IFEvents.BAND_CROSSED`) so
+ * this package stays free of if-domain.
+ */
+export declare function createBandDataWatcher(config: BandCrossingConfig, dataEventId: string): TurnPlugin;
+/** Params handed to a narration message (ADR-262 D4). */
+export interface BandNarrationParams extends Record<string, unknown> {
+    band: string;
+    from: string | null;
+    to: string;
+    count: number;
+    bands: string;
+    value: number;
+}
+export interface BandNarratorConfig extends BandCrossingConfig {
+    mode: BandAnnounceMode;
+    /**
+     * The event id carrying the narration messageId (rendered via ADR-097). Its
+     * payload is `{ messageId, params }`.
+     */
+    narrationEventId: string;
+    /** Message id spoken when a crossed rung has no author phrase (ADR-262 D3). */
+    fallbackPhraseId: string;
+    /** The concept-level span phrase for `combined` mode (ADR-262 D4). */
+    combinedPhraseId?: string;
+    /**
+     * Map a rung + span to message params. Defaults to the generic
+     * {@link BandNarrationParams}; a concept overrides it to match its authored
+     * `says` phrases (scoring keeps `{rank}`/`{score}`).
+     */
+    paramsFor?: (rung: BandRung, span: BandCrossingSpan) => Record<string, unknown>;
+}
+/**
+ * A narrator that renders a crossing under the four announce modes (ADR-262
+ * D3): `all` speaks each crossed band's phrase, `collapsed` only the terminal
+ * band's, `combined` one span message, `silent` nothing. A crossed rung with no
+ * phrase speaks the overridable `fallbackPhraseId`, so silence comes only from
+ * `silent`.
+ */
+export declare function createBandNarrator(config: BandNarratorConfig): TurnPlugin;
+//# sourceMappingURL=band-crossing.d.ts.map

package/band-crossing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"band-crossing.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/band-crossing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAU,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,YAAY,EAAE,QAAQ,EAAE,CAAC;IACzB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC;IAC3C,oDAAoD;IACpD,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;IACrC,sEAAsE;IACtE,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,QAAQ,EAAE,CAAC;IACzC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,2DAA2D;AAC3D,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAmFD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,kBAAkB,EAC1B,WAAW,EAAE,MAAM,GAClB,UAAU,CAWZ;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAoB,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAmB,SAAQ,kBAAkB;IAC5D,IAAI,EAAE,gBAAgB,CAAC;IACvB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,gBAAgB,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,UAAU,CA+BzE"}

package/band-crossing.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * The banded-scalar crossing engine (ADR-262).
+ *
+ * A continuous meter — score, hunger severity, madness — is a number that moves.
+ * As it moves it crosses *bands* (ranks, hunger stages) at absolute thresholds.
+ * This module is the shared machinery that detects those crossings and turns
+ * them into events, so each metering concept keeps only its bespoke Chord
+ * surface and lowers to one engine (ADR-262 D1).
+ *
+ * Two responsibilities, split into two plugin factories over one detector:
+ *
+ *  - {@link createBandDataWatcher} emits the generic **data** event
+ *    `if.event.band_crossed` carrying the whole crossed span (ADR-262 D2). It
+ *    is the always-on part — a TypeScript story reads it and renders promotions
+ *    itself; a Chord story gets it too.
+ *  - {@link createBandNarrator} emits **narration** events carrying a messageId
+ *    under the four verbosity modes (ADR-262 D3). This is the Chord render
+ *    layer; a rung with no author phrase speaks an overridable platform
+ *    fallback, and only `silent` suppresses.
+ *
+ * Both share {@link BandCrossingDetector}: rise-only (ADR-262 D5), the band is
+ * derived from the value every turn via `bandOf`, and the only persisted state
+ * is the last-announced band id, for crossing edge-detection across
+ * save/restore.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBandDataWatcher = createBandDataWatcher;
+exports.createBandNarrator = createBandNarrator;
+const core_1 = require("@sharpee/core");
+const world_model_1 = require("@sharpee/world-model");
+/**
+ * The crossing detector shared by both plugin factories. Holds the
+ * last-announced band id, derives the current band from the value every turn,
+ * and returns the crossed span on a rise (or null: not enabled, no bands, at
+ * the seeded baseline, same band, or a fall).
+ */
+class BandCrossingDetector {
+    config;
+    lastAnnouncedId = null;
+    constructor(config) {
+        this.config = config;
+    }
+    detect(world) {
+        const { config } = this;
+        if (config.isEnabled && !config.isEnabled(world))
+            return null;
+        const bands = config.bands(world);
+        if (bands.length === 0)
+            return null;
+        const value = config.value(world);
+        const currentIndex = (0, world_model_1.bandOf)(value, bands.map(b => b.threshold));
+        // Baseline seed: at/below the start value, adopt the current band silently
+        // so the bottom rung never fires as a promotion (ADR-262, scoring's score<=0).
+        if (config.seedAtOrBelow !== undefined && value <= config.seedAtOrBelow) {
+            this.lastAnnouncedId = currentIndex < 0 ? null : bands[currentIndex].id;
+            return null;
+        }
+        // Below every band: out of the ladder entirely. Reset so a later rise reads
+        // as a fresh crossing from the bottom (hunger recovering below `peckish`).
+        if (currentIndex < 0) {
+            this.lastAnnouncedId = null;
+            return null;
+        }
+        const lastIndex = this.lastAnnouncedId === null
+            ? -1
+            : bands.findIndex(b => b.id === this.lastAnnouncedId);
+        // Rise only (ADR-262 D5). Same band or a fall: track the position so
+        // re-crossing announces again, but say nothing now.
+        if (currentIndex <= lastIndex) {
+            this.lastAnnouncedId = bands[currentIndex].id;
+            return null;
+        }
+        const rungsCrossed = bands.slice(lastIndex + 1, currentIndex + 1);
+        const fromId = lastIndex < 0 ? null : bands[lastIndex].id;
+        const toId = bands[currentIndex].id;
+        this.lastAnnouncedId = toId;
+        return { concept: config.concept, fromId, toId, rungsCrossed, value };
+    }
+    getState() {
+        return { lastAnnouncedId: this.lastAnnouncedId };
+    }
+    setState(state) {
+        this.lastAnnouncedId = state?.lastAnnouncedId ?? null;
+    }
+}
+/** A plugin built from a detector plus an emit strategy. */
+function makePlugin(config, emit) {
+    const detector = new BandCrossingDetector(config);
+    return {
+        id: config.id,
+        priority: config.priority,
+        onAfterAction(ctx) {
+            const span = detector.detect(ctx.world);
+            return span ? emit(span) : [];
+        },
+        getState: () => detector.getState(),
+        setState: (state) => detector.setState(state),
+    };
+}
+/**
+ * A watcher that emits the generic `if.event.band_crossed` data event on a rise
+ * (ADR-262 D2). One event per turn, carrying the whole crossed span, no
+ * messageId. `dataEventId` is passed in (typically `IFEvents.BAND_CROSSED`) so
+ * this package stays free of if-domain.
+ */
+function createBandDataWatcher(config, dataEventId) {
+    return makePlugin(config, (span) => {
+        const data = {
+            concept: span.concept,
+            from: span.fromId,
+            to: span.toId,
+            bandsCrossed: span.rungsCrossed.map(r => r.id),
+            value: span.value,
+        };
+        return [(0, core_1.createEvent)(dataEventId, data)];
+    });
+}
+/**
+ * A narrator that renders a crossing under the four announce modes (ADR-262
+ * D3): `all` speaks each crossed band's phrase, `collapsed` only the terminal
+ * band's, `combined` one span message, `silent` nothing. A crossed rung with no
+ * phrase speaks the overridable `fallbackPhraseId`, so silence comes only from
+ * `silent`.
+ */
+function createBandNarrator(config) {
+    const genericParams = (rung, span) => ({
+        band: rung.name ?? rung.id,
+        from: span.fromId,
+        to: span.toId,
+        count: span.rungsCrossed.length,
+        bands: span.rungsCrossed.map(r => r.name ?? r.id).join(', '),
+        value: span.value,
+    });
+    const paramsFor = config.paramsFor ?? genericParams;
+    const line = (messageId, params) => (0, core_1.createEvent)(config.narrationEventId, { messageId, params });
+    return makePlugin(config, (span) => {
+        switch (config.mode) {
+            case 'silent':
+                return [];
+            case 'all':
+                return span.rungsCrossed.map(rung => line(rung.phraseId ?? config.fallbackPhraseId, paramsFor(rung, span)));
+            case 'collapsed': {
+                const top = span.rungsCrossed[span.rungsCrossed.length - 1];
+                return [line(top.phraseId ?? config.fallbackPhraseId, paramsFor(top, span))];
+            }
+            case 'combined': {
+                const top = span.rungsCrossed[span.rungsCrossed.length - 1];
+                return [line(config.combinedPhraseId ?? config.fallbackPhraseId, genericParams(top, span))];
+            }
+        }
+    });
+}
+//# sourceMappingURL=band-crossing.js.map

package/band-crossing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"band-crossing.js","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/band-crossing.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;AA+JH,sDAcC;AAsCD,gDA+BC;AAhPD,wCAAiE;AACjE,sDAA+D;AAqE/D;;;;;GAKG;AACH,MAAM,oBAAoB;IAGK;IAFrB,eAAe,GAAkB,IAAI,CAAC;IAE9C,YAA6B,MAA0B;QAA1B,WAAM,GAAN,MAAM,CAAoB;IAAG,CAAC;IAE3D,MAAM,CAAC,KAAiB;QACtB,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;QACxB,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAE9D,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAEpC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClC,MAAM,YAAY,GAAG,IAAA,oBAAM,EAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;QAEhE,2EAA2E;QAC3E,+EAA+E;QAC/E,IAAI,MAAM,CAAC,aAAa,KAAK,SAAS,IAAI,KAAK,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;YACxE,IAAI,CAAC,eAAe,GAAG,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;YACxE,OAAO,IAAI,CAAC;QACd,CAAC;QAED,4EAA4E;QAC5E,2EAA2E;QAC3E,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;YAC5B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,KAAK,IAAI;YAC7C,CAAC,CAAC,CAAC,CAAC;YACJ,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,eAAe,CAAC,CAAC;QAExD,qEAAqE;QACrE,oDAAoD;QACpD,IAAI,YAAY,IAAI,SAAS,EAAE,CAAC;YAC9B,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;YAC9C,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,SAAS,GAAG,CAAC,EAAE,YAAY,GAAG,CAAC,CAAC,CAAC;QAClE,MAAM,MAAM,GAAG,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC;QAC1D,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACpC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAE5B,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IACxE,CAAC;IAED,QAAQ;QACN,OAAO,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC;IACnD,CAAC;IAED,QAAQ,CAAC,KAAc;QACrB,IAAI,CAAC,eAAe,GAAI,KAAsC,EAAE,eAAe,IAAI,IAAI,CAAC;IAC1F,CAAC;CACF;AAED,4DAA4D;AAC5D,SAAS,UAAU,CACjB,MAA0B,EAC1B,IAAkD;IAElD,MAAM,QAAQ,GAAG,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAClD,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,QAAQ,EAAE,MAAM,CAAC,QAAQ;QACzB,aAAa,CAAC,GAAsB;YAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YACxC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChC,CAAC;QACD,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE;QACnC,QAAQ,EAAE,CAAC,KAAc,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC;KACvD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CACnC,MAA0B,EAC1B,WAAmB;IAEnB,OAAO,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACjC,MAAM,IAAI,GAAoB;YAC5B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,MAAM;YACjB,EAAE,EAAE,IAAI,CAAC,IAAI;YACb,YAAY,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;QACF,OAAO,CAAC,IAAA,kBAAW,EAAC,WAAW,EAAE,IAA0C,CAAC,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;AACL,CAAC;AA+BD;;;;;;GAMG;AACH,SAAgB,kBAAkB,CAAC,MAA0B;IAC3D,MAAM,aAAa,GAAG,CAAC,IAAc,EAAE,IAAsB,EAAuB,EAAE,CAAC,CAAC;QACtF,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE;QAC1B,IAAI,EAAE,IAAI,CAAC,MAAM;QACjB,EAAE,EAAE,IAAI,CAAC,IAAI;QACb,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,MAAM;QAC/B,KAAK,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC5D,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,aAAa,CAAC;IAEpD,MAAM,IAAI,GAAG,CAAC,SAAiB,EAAE,MAA+B,EAAkB,EAAE,CAClF,IAAA,kBAAW,EAAC,MAAM,CAAC,gBAAgB,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;IAE9D,OAAO,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;QACjC,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,KAAK,QAAQ;gBACX,OAAO,EAAE,CAAC;YACZ,KAAK,KAAK;gBACR,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAClC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,gBAAgB,EAAE,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAC3E,KAAK,WAAW,CAAC,CAAC,CAAC;gBACjB,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBAC5D,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,MAAM,CAAC,gBAAgB,EAAE,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAC/E,CAAC;YACD,KAAK,UAAU,CAAC,CAAC,CAAC;gBAChB,MAAM,GAAG,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;gBAC5D,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,IAAI,MAAM,CAAC,gBAAgB,EAAE,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9F,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/index.d.ts

@@ -1,4 +1,6 @@
-export { TurnPlugin } from './turn-plugin';
-export { TurnPluginContext, TurnPluginActionResult } from './turn-plugin-context';
-export { PluginRegistry } from './plugin-registry';
+export { TurnPlugin } from './turn-plugin.js';
+export { TurnPluginContext, TurnPluginActionResult } from './turn-plugin-context.js';
+export { PluginRegistry } from './plugin-registry.js';
+export { createBandDataWatcher, createBandNarrator, } from './band-crossing.js';
+export type { BandAnnounceMode, BandRung, BandCrossingSpan, BandCrossedData, BandCrossingConfig, BandWatcherState, BandNarrationParams, BandNarratorConfig, } from './band-crossing.js';
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,EACL,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,gBAAgB,EAChB,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC"}

package/index.js

@@ -1,6 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PluginRegistry = void 0;
-var plugin_registry_1 = require("./plugin-registry");
-Object.defineProperty(exports, "PluginRegistry", { enumerable: true, get: function () { return plugin_registry_1.PluginRegistry; } });
+exports.createBandNarrator = exports.createBandDataWatcher = exports.PluginRegistry = void 0;
+var plugin_registry_js_1 = require("./plugin-registry.js");
+Object.defineProperty(exports, "PluginRegistry", { enumerable: true, get: function () { return plugin_registry_js_1.PluginRegistry; } });
+// Banded-scalar crossing engine (ADR-262)
+var band_crossing_js_1 = require("./band-crossing.js");
+Object.defineProperty(exports, "createBandDataWatcher", { enumerable: true, get: function () { return band_crossing_js_1.createBandDataWatcher; } });
+Object.defineProperty(exports, "createBandNarrator", { enumerable: true, get: function () { return band_crossing_js_1.createBandNarrator; } });
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/index.ts"],"names":[],"mappings":";;;AAEA,qDAAmD;AAA1C,iHAAA,cAAc,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/index.ts"],"names":[],"mappings":";;;AAEA,2DAAsD;AAA7C,oHAAA,cAAc,OAAA;AAEvB,0CAA0C;AAC1C,uDAG4B;AAF1B,yHAAA,qBAAqB,OAAA;AACrB,sHAAA,kBAAkB,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sharpee/plugins",
-  "version": "3.1.0",
+  "version": "3.5.0",
   "description": "Plugin contracts for Sharpee engine turn-cycle extensibility",
   "main": "./index.js",
   "types": "./index.d.ts",
@@ -12,8 +12,8 @@
     }
   },
   "dependencies": {
-    "@sharpee/core": "^3.1.0",
-    "@sharpee/world-model": "^3.1.0"
+    "@sharpee/core": "^3.5.0",
+    "@sharpee/world-model": "^3.5.0"
   },
   "keywords": [
     "interactive-fiction",

package/plugin-registry.d.ts

@@ -1,4 +1,4 @@
-import { TurnPlugin } from './turn-plugin';
+import { TurnPlugin } from './turn-plugin.js';
 /**
  * Holds the turn plugins for a running game and hands them to the engine in
  * priority order each turn (ADR-120). The engine owns the single registry;

package/plugin-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/plugin-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAsC;IAErD,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAOlC,sEAAsE;IACtE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI5B,qCAAqC;IACrC,KAAK,IAAI,IAAI;IAIb,8EAA8E;IAC9E,MAAM,IAAI,UAAU,EAAE;IAMtB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI3C;;;OAGG;IACH,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUpC;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAQjD"}
+{"version":3,"file":"plugin-registry.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/plugin-registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,OAAO,CAAsC;IAErD,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAOlC,sEAAsE;IACtE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAI5B,qCAAqC;IACrC,KAAK,IAAI,IAAI;IAIb,8EAA8E;IAC9E,MAAM,IAAI,UAAU,EAAE;IAMtB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAI3C;;;OAGG;IACH,SAAS,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAUpC;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAQjD"}

package/turn-plugin-context.d.ts

@@ -4,7 +4,15 @@ import { WorldModel } from '@sharpee/world-model';
 export interface TurnPluginActionResult {
     /** The action's id (the verb that ran). */
     actionId: string;
-    /** Whether the action succeeded. Plugins only run after successful actions. */
+    /**
+     * Whether the action GENUINELY succeeded (platform-issue-sweep Phase 7):
+     * false when the action was refused/blocked — including modern blocked()
+     * paths that reuse the primary event type with `blocked: true` /
+     * `failed: true` instead of emitting `action.error`. Plugins still run
+     * after refused actions (NPC/scheduler ticks are turn-level); consumers
+     * that must not react to refusals (state-machine action triggers) gate on
+     * this flag.
+     */
     success: boolean;
     /** The action's direct-object entity, when it had one. */
     targetId?: EntityId;

package/turn-plugin-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-plugin-context.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/turn-plugin-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,wCAAwC;IACxC,cAAc,EAAE,QAAQ,CAAC;IACzB;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB,gDAAgD;IAChD,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,wDAAwD;IACxD,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;CACjC"}
+{"version":3,"file":"turn-plugin-context.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/turn-plugin-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;;;;OAQG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,wCAAwC;IACxC,cAAc,EAAE,QAAQ,CAAC;IACzB;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB,gDAAgD;IAChD,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,wDAAwD;IACxD,YAAY,CAAC,EAAE,cAAc,EAAE,CAAC;CACjC"}

package/turn-plugin.d.ts

@@ -1,5 +1,5 @@
 import { ISemanticEvent } from '@sharpee/core';
-import { TurnPluginContext } from './turn-plugin-context';
+import { TurnPluginContext } from './turn-plugin-context.js';
 /**
  * A turn-cycle plugin: code that runs once after each successful player action
  * to contribute additional world changes and events (ADR-120).

package/turn-plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"turn-plugin.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/turn-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAAC;IAC5D,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,OAAO,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC"}
+{"version":3,"file":"turn-plugin.d.ts","sourceRoot":"","sources":["../../../../../../repos/sharpee_v2/packages/plugins/src/turn-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,iFAAiF;IACjF,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,OAAO,EAAE,iBAAiB,GAAG,cAAc,EAAE,CAAC;IAC5D,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,OAAO,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC"}