@flighthq/statechart 0.3.0-next.1728.26853f6

package/dist/contract.d.ts

@@ -0,0 +1,4 @@
+export * from './enableStatechartGuards';
+export * from './statechart';
+export * from './statechartSignals';
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC"}

package/dist/contract.js

@@ -0,0 +1,4 @@
+export * from './enableStatechartGuards';
+export * from './statechart';
+export * from './statechartSignals';
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC"}

package/dist/enableStatechartGuards.d.ts

@@ -0,0 +1,5 @@
+import type { StatechartInstance } from '@flighthq/types/contract';
+export declare function areStatechartGuardsEnabled(instance: Readonly<StatechartInstance>): boolean;
+export declare function disableStatechartGuards(instance: StatechartInstance): void;
+export declare function enableStatechartGuards(instance: StatechartInstance): void;
+//# sourceMappingURL=enableStatechartGuards.d.ts.map

package/dist/enableStatechartGuards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableStatechartGuards.d.ts","sourceRoot":"","sources":["../src/enableStatechartGuards.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAmC,MAAM,0BAA0B,CAAC;AAGpG,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,OAAO,CAE1F;AAGD,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAE1E;AAKD,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAEzE"}

package/dist/enableStatechartGuards.js

@@ -0,0 +1,40 @@
+import { logOnce } from '@flighthq/log/contract';
+import { LogLevel } from '@flighthq/types/contract';
+// Report whether caller-misuse diagnostics are installed for this actor.
+export function areStatechartGuardsEnabled(instance) {
+    return instance.durationGuard === warnMissingStatechartRegionDuration;
+}
+// Remove the opt-in diagnostics hook without changing transition behavior.
+export function disableStatechartGuards(instance) {
+    instance.durationGuard = null;
+}
+// Install state-scoped warnings for exit-time transitions whose composition layer never supplied a
+// positive state duration. Core still coerces that gate to no requirement; this module owns the message
+// and @flighthq/log dependency, so an unguarded count/read consumer sheds both completely.
+export function enableStatechartGuards(instance) {
+    instance.durationGuard = warnMissingStatechartRegionDuration;
+}
+function warnMissingStatechartRegionDuration(instance, explanation) {
+    const chartId = getStatechartGuardChartId(instance.chart);
+    logOnce(`statechart:missing-region-duration:${chartId}:${explanation.regionIndex}:${explanation.sourceStateIndex}:${explanation.transitionIndex}`, LogLevel.Warn, {
+        exitTimeRatio: instance.chart.regions[explanation.regionIndex]?.states[explanation.sourceStateIndex]?.transitions[explanation.transitionIndex]?.exitTimeRatio ?? -1,
+        message: 'advanceStatechartInstance: exitTimeRatio requires a positive region duration; the transition was treated as having no exit-time requirement — call setStatechartRegionDuration when the region enters a state.',
+        regionDuration: instance.regionDuration[explanation.regionIndex] ?? -1,
+        regionIndex: explanation.regionIndex,
+        sourceStateIndex: explanation.sourceStateIndex,
+        status: explanation.status,
+        targetStateIndex: explanation.targetStateIndex,
+        transitionIndex: explanation.transitionIndex,
+    }, 'statechart');
+}
+function getStatechartGuardChartId(chart) {
+    let id = statechartGuardChartIds.get(chart);
+    if (id === undefined) {
+        id = nextStatechartGuardChartId++;
+        statechartGuardChartIds.set(chart, id);
+    }
+    return id;
+}
+const statechartGuardChartIds = new WeakMap();
+let nextStatechartGuardChartId = 1;
+//# sourceMappingURL=enableStatechartGuards.js.map

package/dist/enableStatechartGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enableStatechartGuards.js","sourceRoot":"","sources":["../src/enableStatechartGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAGpD,yEAAyE;AACzE,MAAM,UAAU,0BAA0B,CAAC,QAAsC;IAC/E,OAAO,QAAQ,CAAC,aAAa,KAAK,mCAAmC,CAAC;AACxE,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,uBAAuB,CAAC,QAA4B;IAClE,QAAQ,CAAC,aAAa,GAAG,IAAI,CAAC;AAChC,CAAC;AAED,mGAAmG;AACnG,wGAAwG;AACxG,2FAA2F;AAC3F,MAAM,UAAU,sBAAsB,CAAC,QAA4B;IACjE,QAAQ,CAAC,aAAa,GAAG,mCAAmC,CAAC;AAC/D,CAAC;AAED,SAAS,mCAAmC,CAC1C,QAAsC,EACtC,WAAsD;IAEtD,MAAM,OAAO,GAAG,yBAAyB,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1D,OAAO,CACL,sCAAsC,OAAO,IAAI,WAAW,CAAC,WAAW,IAAI,WAAW,CAAC,gBAAgB,IAAI,WAAW,CAAC,eAAe,EAAE,EACzI,QAAQ,CAAC,IAAI,EACb;QACE,aAAa,EACX,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC,EAAE,WAAW,CAChG,WAAW,CAAC,eAAe,CAC5B,EAAE,aAAa,IAAI,CAAC,CAAC;QACxB,OAAO,EACL,gNAAgN;QAClN,cAAc,EAAE,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QACtE,WAAW,EAAE,WAAW,CAAC,WAAW;QACpC,gBAAgB,EAAE,WAAW,CAAC,gBAAgB;QAC9C,MAAM,EAAE,WAAW,CAAC,MAAM;QAC1B,gBAAgB,EAAE,WAAW,CAAC,gBAAgB;QAC9C,eAAe,EAAE,WAAW,CAAC,eAAe;KAC7C,EACD,YAAY,CACb,CAAC;AACJ,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAuB;IACxD,IAAI,EAAE,GAAG,uBAAuB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,EAAE,GAAG,0BAA0B,EAAE,CAAC;QAClC,uBAAuB,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,uBAAuB,GAAG,IAAI,OAAO,EAAkB,CAAC;AAC9D,IAAI,0BAA0B,GAAG,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { areStatechartGuardsEnabled, disableStatechartGuards, enableStatechartGuards } from './enableStatechartGuards';
+export { advanceStatechartInstance, createStatechartInstance, explainStatechartTransition, fireStatechartTrigger, getStatechartInputIndex, getStatechartRegionBlend, getStatechartRegionState, setStatechartBooleanInput, setStatechartNumberInput, setStatechartRegionDuration, } from './statechart';
+export { enableStatechartSignals, getStatechartSignals } from './statechartSignals';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvH,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,EAC3B,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { areStatechartGuardsEnabled, disableStatechartGuards, enableStatechartGuards } from './enableStatechartGuards';
+export { advanceStatechartInstance, createStatechartInstance, explainStatechartTransition, fireStatechartTrigger, getStatechartInputIndex, getStatechartRegionBlend, getStatechartRegionState, setStatechartBooleanInput, setStatechartNumberInput, setStatechartRegionDuration, } from './statechart';
+export { enableStatechartSignals, getStatechartSignals } from './statechartSignals';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AACvH,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,EAC3B,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,yBAAyB,EACzB,wBAAwB,EACxB,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/statechart.d.ts

@@ -0,0 +1,12 @@
+import type { Statechart, StatechartInstance, StatechartTransitionExplanation } from '@flighthq/types/contract';
+export declare function advanceStatechartInstance(instance: StatechartInstance, deltaTime: number): number;
+export declare function createStatechartInstance(chart: Readonly<Statechart>): StatechartInstance;
+export declare function explainStatechartTransition(instance: Readonly<StatechartInstance>, regionIndex: number): StatechartTransitionExplanation;
+export declare function fireStatechartTrigger(instance: StatechartInstance, inputIndex: number): void;
+export declare function getStatechartInputIndex(chart: Readonly<Statechart>, name: string): number;
+export declare function getStatechartRegionBlend(instance: Readonly<StatechartInstance>, regionIndex: number): number;
+export declare function getStatechartRegionState(instance: Readonly<StatechartInstance>, regionIndex: number): number;
+export declare function setStatechartBooleanInput(instance: StatechartInstance, inputIndex: number, value: boolean): void;
+export declare function setStatechartNumberInput(instance: StatechartInstance, inputIndex: number, value: number): void;
+export declare function setStatechartRegionDuration(instance: StatechartInstance, regionIndex: number, duration: number): void;
+//# sourceMappingURL=statechart.d.ts.map

package/dist/statechart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statechart.d.ts","sourceRoot":"","sources":["../src/statechart.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,UAAU,EAEV,kBAAkB,EAElB,+BAA+B,EAChC,MAAM,0BAA0B,CAAC;AAMlC,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CA0BjG;AAKD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,kBAAkB,CAiCxF;AAKD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EACtC,WAAW,EAAE,MAAM,GAClB,+BAA+B,CAuFjC;AAID,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAG5F;AAID,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKzF;AAID,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5G;AAGD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE5G;AAGD,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAGhH;AAID,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAG9G;AAKD,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQrH"}

package/dist/statechart.js

@@ -0,0 +1,369 @@
+import { StatechartComparison, StatechartInputKind, StatechartTransitionStatus } from '@flighthq/types/contract';
+// Advance every concurrent region by `deltaTime` milliseconds and return how many reached a new
+// state. Each region changes at most once per call. Trigger inputs are edge latches shared by all
+// regions for the whole pass, then cleared, so one fired trigger can independently drive several
+// regions. Blend progress is reported as a number only; this package never samples or blends content.
+export function advanceStatechartInstance(instance, deltaTime) {
+    const deltaTimeMs = Number.isFinite(deltaTime) && deltaTime > 0 ? deltaTime : 0;
+    let changedRegions = null;
+    let changedRegionCount = 0;
+    for (let regionIndex = 0; regionIndex < instance.chart.regions.length; regionIndex++) {
+        const previousStateIndex = instance.regionStates[regionIndex];
+        if (advanceStatechartRegion(instance, regionIndex, deltaTimeMs)) {
+            changedRegionCount++;
+            // Observer allocation is opt-in and occurs only when a state actually changes. Pairs are
+            // [regionIndex, previousStateIndex]; the new state is already in regionStates.
+            if (instance.signals !== null)
+                (changedRegions ??= []).push(regionIndex, previousStateIndex);
+        }
+    }
+    // Clear before emitting: a listener may fire a trigger for the NEXT pass, and that edge must not be
+    // erased by cleanup from this pass. Deferring every emit also prevents a region-0 listener from
+    // mutating an input while later concurrent regions are still evaluating the shared input snapshot.
+    clearStatechartTriggers(instance);
+    if (changedRegions !== null && instance.signals !== null) {
+        for (let i = 0; i < changedRegions.length; i += 2) {
+            const regionIndex = changedRegions[i];
+            instance.signals.onStateChange.emit(regionIndex, changedRegions[i + 1], instance.regionStates[regionIndex]);
+        }
+    }
+    return changedRegionCount;
+}
+// Allocate the mutable per-actor half of `chart`. The chart itself is retained by reference and is
+// never mutated; input and region state live in independent typed arrays so one chart can drive many
+// actors. Malformed authored indices/kinds are programmer errors and fail at this construction seam.
+export function createStatechartInstance(chart) {
+    validateStatechart(chart);
+    const inputValues = new Float64Array(chart.inputs.length);
+    for (let inputIndex = 0; inputIndex < chart.inputs.length; inputIndex++) {
+        const input = chart.inputs[inputIndex];
+        inputValues[inputIndex] =
+            input.kind === StatechartInputKind.Boolean ? (input.initialValue === 0 ? 0 : 1) : input.initialValue;
+    }
+    const regionCount = chart.regions.length;
+    const regionBlend = new Float32Array(regionCount);
+    const regionDuration = new Float64Array(regionCount);
+    const regionElapsed = new Float64Array(regionCount);
+    const regionStates = new Int32Array(regionCount);
+    const regionTransitions = new Int32Array(regionCount);
+    regionTransitions.fill(-1);
+    for (let regionIndex = 0; regionIndex < regionCount; regionIndex++) {
+        regionStates[regionIndex] = chart.regions[regionIndex].initialStateIndex;
+    }
+    return {
+        chart,
+        durationGuard: null,
+        inputValues,
+        regionBlend,
+        regionDuration,
+        regionElapsed,
+        regionStates,
+        regionTransitions,
+        signals: null,
+    };
+}
+// Explain what the next advance sees in one region. This is the shakeable diagnostic companion to
+// sentinel/count-based runtime calls: it reports an active blend, the first ready transition, or the
+// first authored transition's blocking condition/exit time without mutating the instance.
+export function explainStatechartTransition(instance, regionIndex) {
+    const region = instance.chart.regions[regionIndex];
+    if (region === undefined)
+        return invalidRegionExplanation(regionIndex);
+    const sourceStateIndex = instance.regionStates[regionIndex];
+    const state = region.states[sourceStateIndex];
+    if (state === undefined)
+        return invalidRegionExplanation(regionIndex);
+    const activeTransitionIndex = instance.regionTransitions[regionIndex];
+    if (activeTransitionIndex >= 0) {
+        const activeTransition = state.transitions[activeTransitionIndex];
+        if (activeTransition === undefined)
+            return invalidRegionExplanation(regionIndex);
+        return {
+            blend: instance.regionBlend[regionIndex],
+            conditionIndex: -1,
+            regionIndex,
+            sourceStateIndex,
+            status: StatechartTransitionStatus.Transitioning,
+            targetStateIndex: activeTransition.targetStateIndex,
+            transitionIndex: activeTransitionIndex,
+        };
+    }
+    if (state.transitions.length === 0) {
+        return {
+            blend: 0,
+            conditionIndex: -1,
+            regionIndex,
+            sourceStateIndex,
+            status: StatechartTransitionStatus.NoTransitions,
+            targetStateIndex: -1,
+            transitionIndex: -1,
+        };
+    }
+    let firstBlocked = null;
+    for (let transitionIndex = 0; transitionIndex < state.transitions.length; transitionIndex++) {
+        const transition = state.transitions[transitionIndex];
+        const conditionIndex = getFirstUnmetCondition(instance, transition);
+        if (conditionIndex >= 0) {
+            firstBlocked ??= {
+                blend: 0,
+                conditionIndex,
+                regionIndex,
+                sourceStateIndex,
+                status: StatechartTransitionStatus.ConditionsUnmet,
+                targetStateIndex: transition.targetStateIndex,
+                transitionIndex,
+            };
+            continue;
+        }
+        const exitStatus = getStatechartExitStatus(instance, regionIndex, transition);
+        if (exitStatus === StatechartTransitionStatus.MissingRegionDuration) {
+            return {
+                blend: 0,
+                conditionIndex: -1,
+                regionIndex,
+                sourceStateIndex,
+                status: StatechartTransitionStatus.MissingRegionDuration,
+                targetStateIndex: transition.targetStateIndex,
+                transitionIndex,
+            };
+        }
+        if (exitStatus === StatechartTransitionStatus.ExitTimePending) {
+            firstBlocked ??= {
+                blend: 0,
+                conditionIndex: -1,
+                regionIndex,
+                sourceStateIndex,
+                status: StatechartTransitionStatus.ExitTimePending,
+                targetStateIndex: transition.targetStateIndex,
+                transitionIndex,
+            };
+            continue;
+        }
+        return {
+            blend: 0,
+            conditionIndex: -1,
+            regionIndex,
+            sourceStateIndex,
+            status: StatechartTransitionStatus.Ready,
+            targetStateIndex: transition.targetStateIndex,
+            transitionIndex,
+        };
+    }
+    return firstBlocked;
+}
+// Latch a Trigger input for the next whole-region advance. Trigger conditions ignore their authored
+// comparison/value and test only this latch. Invalid indices and kind mismatches are programmer errors.
+export function fireStatechartTrigger(instance, inputIndex) {
+    assertStatechartInputKind(instance, inputIndex, StatechartInputKind.Trigger);
+    instance.inputValues[inputIndex] = 1;
+}
+// Return the first input with `name`, or -1 when it is absent. Authored duplicate names deliberately
+// preserve array/serialization order rather than building hidden lookup state.
+export function getStatechartInputIndex(chart, name) {
+    for (let inputIndex = 0; inputIndex < chart.inputs.length; inputIndex++) {
+        if (chart.inputs[inputIndex].name === name)
+            return inputIndex;
+    }
+    return -1;
+}
+// Return one concurrent region's target-state blend weight in [0, 1], or -1 for an invalid region.
+// The composition layer decides what the plain number means; statechart performs no animation work.
+export function getStatechartRegionBlend(instance, regionIndex) {
+    return regionIndex >= 0 && regionIndex < instance.regionBlend.length ? instance.regionBlend[regionIndex] : -1;
+}
+// Return one concurrent region's current source-state index, or -1 for an invalid region.
+export function getStatechartRegionState(instance, regionIndex) {
+    return regionIndex >= 0 && regionIndex < instance.regionStates.length ? instance.regionStates[regionIndex] : -1;
+}
+// Write a Boolean input as the numeric 0/1 vocabulary used by data-only transition conditions.
+export function setStatechartBooleanInput(instance, inputIndex, value) {
+    assertStatechartInputKind(instance, inputIndex, StatechartInputKind.Boolean);
+    instance.inputValues[inputIndex] = value ? 1 : 0;
+}
+// Write a Number input. Numbers remain exact authored/runtime values; comparisons happen only while
+// selecting a transition.
+export function setStatechartNumberInput(instance, inputIndex, value) {
+    assertStatechartInputKind(instance, inputIndex, StatechartInputKind.Number);
+    instance.inputValues[inputIndex] = value;
+}
+// Supply the current state's duration for exit-time evaluation, in the same millisecond unit as
+// advanceStatechartInstance. The composition layer owns what the duration means and where it came from;
+// statechart only divides elapsed time by this plain number. Zero explicitly marks duration unavailable.
+export function setStatechartRegionDuration(instance, regionIndex, duration) {
+    if (!Number.isInteger(regionIndex) || regionIndex < 0 || regionIndex >= instance.regionDuration.length) {
+        throw new RangeError(`Statechart region index ${regionIndex} is out of range`);
+    }
+    if (!Number.isFinite(duration) || duration < 0) {
+        throw new RangeError('Statechart region duration must be finite and non-negative');
+    }
+    instance.regionDuration[regionIndex] = duration;
+}
+function advanceStatechartRegion(instance, regionIndex, deltaTimeMs) {
+    const region = instance.chart.regions[regionIndex];
+    const sourceStateIndex = instance.regionStates[regionIndex];
+    const sourceState = region.states[sourceStateIndex];
+    if (sourceState === undefined)
+        throw new RangeError(`Statechart region ${regionIndex} has an invalid active state`);
+    instance.regionElapsed[regionIndex] += deltaTimeMs;
+    let transitionIndex = instance.regionTransitions[regionIndex];
+    let transition;
+    if (transitionIndex >= 0) {
+        transition = sourceState.transitions[transitionIndex];
+        if (transition === undefined) {
+            throw new RangeError(`Statechart region ${regionIndex} has an invalid active transition`);
+        }
+    }
+    else {
+        transitionIndex = getReadyTransitionIndex(instance, regionIndex);
+        if (transitionIndex < 0)
+            return false;
+        transition = sourceState.transitions[transitionIndex];
+        instance.regionTransitions[regionIndex] = transitionIndex;
+        instance.regionBlend[regionIndex] = 0;
+    }
+    const durationMs = Number.isFinite(transition.durationMs) && transition.durationMs > 0 ? transition.durationMs : 0;
+    const blend = durationMs === 0 ? 1 : Math.min(1, instance.regionBlend[regionIndex] + deltaTimeMs / durationMs);
+    instance.regionBlend[regionIndex] = blend;
+    if (blend < 1)
+        return false;
+    instance.regionStates[regionIndex] = transition.targetStateIndex;
+    instance.regionTransitions[regionIndex] = -1;
+    instance.regionBlend[regionIndex] = 0;
+    instance.regionDuration[regionIndex] = 0;
+    instance.regionElapsed[regionIndex] = 0;
+    return true;
+}
+function assertStatechartInputKind(instance, inputIndex, expectedKind) {
+    const input = instance.chart.inputs[inputIndex];
+    if (input === undefined)
+        throw new RangeError(`Statechart input index ${inputIndex} is out of range`);
+    if (input.kind !== expectedKind) {
+        throw new TypeError(`Statechart input ${inputIndex} is ${input.kind}, not ${expectedKind}`);
+    }
+}
+function clearStatechartTriggers(instance) {
+    for (let inputIndex = 0; inputIndex < instance.chart.inputs.length; inputIndex++) {
+        if (instance.chart.inputs[inputIndex].kind === StatechartInputKind.Trigger)
+            instance.inputValues[inputIndex] = 0;
+    }
+}
+function compareStatechartCondition(value, condition) {
+    switch (condition.comparison) {
+        case StatechartComparison.Equal:
+            return value === condition.value;
+        case StatechartComparison.GreaterThan:
+            return value > condition.value;
+        case StatechartComparison.GreaterThanOrEqual:
+            return value >= condition.value;
+        case StatechartComparison.LessThan:
+            return value < condition.value;
+        case StatechartComparison.LessThanOrEqual:
+            return value <= condition.value;
+        case StatechartComparison.NotEqual:
+            return value !== condition.value;
+    }
+}
+function getFirstUnmetCondition(instance, transition) {
+    for (let conditionIndex = 0; conditionIndex < transition.conditions.length; conditionIndex++) {
+        const condition = transition.conditions[conditionIndex];
+        const input = instance.chart.inputs[condition.inputIndex];
+        if (input === undefined)
+            return conditionIndex;
+        const inputValue = instance.inputValues[condition.inputIndex];
+        const met = input.kind === StatechartInputKind.Trigger ? inputValue !== 0 : compareStatechartCondition(inputValue, condition);
+        if (!met)
+            return conditionIndex;
+    }
+    return -1;
+}
+function getReadyTransitionIndex(instance, regionIndex) {
+    const region = instance.chart.regions[regionIndex];
+    const state = region.states[instance.regionStates[regionIndex]];
+    for (let transitionIndex = 0; transitionIndex < state.transitions.length; transitionIndex++) {
+        const transition = state.transitions[transitionIndex];
+        if (getFirstUnmetCondition(instance, transition) >= 0)
+            continue;
+        const exitStatus = getStatechartExitStatus(instance, regionIndex, transition);
+        if (exitStatus === StatechartTransitionStatus.ExitTimePending)
+            continue;
+        if (exitStatus === StatechartTransitionStatus.MissingRegionDuration) {
+            instance.durationGuard?.(instance, {
+                blend: 0,
+                conditionIndex: -1,
+                regionIndex,
+                sourceStateIndex: instance.regionStates[regionIndex],
+                status: StatechartTransitionStatus.MissingRegionDuration,
+                targetStateIndex: transition.targetStateIndex,
+                transitionIndex,
+            });
+        }
+        return transitionIndex;
+    }
+    return -1;
+}
+function getStatechartExitStatus(instance, regionIndex, transition) {
+    if (transition.exitTimeRatio < 0)
+        return StatechartTransitionStatus.Ready;
+    const duration = instance.regionDuration[regionIndex];
+    if (duration <= 0)
+        return StatechartTransitionStatus.MissingRegionDuration;
+    return instance.regionElapsed[regionIndex] / duration >= transition.exitTimeRatio
+        ? StatechartTransitionStatus.Ready
+        : StatechartTransitionStatus.ExitTimePending;
+}
+function invalidRegionExplanation(regionIndex) {
+    return {
+        blend: -1,
+        conditionIndex: -1,
+        regionIndex,
+        sourceStateIndex: -1,
+        status: StatechartTransitionStatus.InvalidRegion,
+        targetStateIndex: -1,
+        transitionIndex: -1,
+    };
+}
+function validateStatechart(chart) {
+    for (let inputIndex = 0; inputIndex < chart.inputs.length; inputIndex++) {
+        const kind = chart.inputs[inputIndex].kind;
+        if (kind !== StatechartInputKind.Boolean &&
+            kind !== StatechartInputKind.Number &&
+            kind !== StatechartInputKind.Trigger) {
+            throw new TypeError(`Statechart input ${inputIndex} has unknown kind ${String(kind)}`);
+        }
+    }
+    for (let regionIndex = 0; regionIndex < chart.regions.length; regionIndex++) {
+        const region = chart.regions[regionIndex];
+        if (region.initialStateIndex < 0 || region.initialStateIndex >= region.states.length) {
+            throw new RangeError(`Statechart region ${regionIndex} has an invalid initialStateIndex`);
+        }
+        for (let stateIndex = 0; stateIndex < region.states.length; stateIndex++) {
+            const state = region.states[stateIndex];
+            if (typeof state.kind !== 'string' || state.kind.length === 0) {
+                throw new TypeError(`Statechart region ${regionIndex} state ${stateIndex} has an invalid kind`);
+            }
+            for (let transitionIndex = 0; transitionIndex < state.transitions.length; transitionIndex++) {
+                const transition = state.transitions[transitionIndex];
+                if (!Number.isFinite(transition.durationMs) || transition.durationMs < 0) {
+                    throw new RangeError(`Statechart region ${regionIndex} state ${stateIndex} transition ${transitionIndex} has an invalid duration`);
+                }
+                if (!Number.isFinite(transition.exitTimeRatio) || transition.exitTimeRatio < -1) {
+                    throw new RangeError(`Statechart region ${regionIndex} state ${stateIndex} transition ${transitionIndex} has an invalid exit time`);
+                }
+                if (transition.targetStateIndex < 0 || transition.targetStateIndex >= region.states.length) {
+                    throw new RangeError(`Statechart region ${regionIndex} state ${stateIndex} transition ${transitionIndex} has an invalid target`);
+                }
+                for (let conditionIndex = 0; conditionIndex < transition.conditions.length; conditionIndex++) {
+                    const condition = transition.conditions[conditionIndex];
+                    const inputIndex = condition.inputIndex;
+                    if (!Number.isInteger(inputIndex) || inputIndex < 0 || inputIndex >= chart.inputs.length) {
+                        throw new RangeError(`Statechart region ${regionIndex} state ${stateIndex} transition ${transitionIndex} has an invalid input`);
+                    }
+                    if (!Object.values(StatechartComparison).includes(condition.comparison)) {
+                        throw new TypeError(`Statechart region ${regionIndex} state ${stateIndex} transition ${transitionIndex} has an invalid comparison`);
+                    }
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=statechart.js.map

package/dist/statechart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statechart.js","sourceRoot":"","sources":["../src/statechart.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AASjH,gGAAgG;AAChG,kGAAkG;AAClG,iGAAiG;AACjG,sGAAsG;AACtG,MAAM,UAAU,yBAAyB,CAAC,QAA4B,EAAE,SAAiB;IACvF,MAAM,WAAW,GAAG,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAChF,IAAI,cAAc,GAAoB,IAAI,CAAC;IAC3C,IAAI,kBAAkB,GAAG,CAAC,CAAC;IAE3B,KAAK,IAAI,WAAW,GAAG,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,CAAC;QACrF,MAAM,kBAAkB,GAAG,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;QAC9D,IAAI,uBAAuB,CAAC,QAAQ,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC;YAChE,kBAAkB,EAAE,CAAC;YACrB,yFAAyF;YACzF,+EAA+E;YAC/E,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI;gBAAE,CAAC,cAAc,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,kBAAkB,CAAC,CAAC;QAC/F,CAAC;IACH,CAAC;IAED,oGAAoG;IACpG,gGAAgG;IAChG,mGAAmG;IACnG,uBAAuB,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,cAAc,KAAK,IAAI,IAAI,QAAQ,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QACzD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;YAClD,MAAM,WAAW,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;YACtC,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC;QAC9G,CAAC;IACH,CAAC;IACD,OAAO,kBAAkB,CAAC;AAC5B,CAAC;AAED,mGAAmG;AACnG,qGAAqG;AACrG,qGAAqG;AACrG,MAAM,UAAU,wBAAwB,CAAC,KAA2B;IAClE,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAE1B,MAAM,WAAW,GAAG,IAAI,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC1D,KAAK,IAAI,UAAU,GAAG,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC;QACxE,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACvC,WAAW,CAAC,UAAU,CAAC;YACrB,KAAK,CAAC,IAAI,KAAK,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC;IACzG,CAAC;IAED,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;IACzC,MAAM,WAAW,GAAG,IAAI,YAAY,CAAC,WAAW,CAAC,CAAC;IAClD,MAAM,cAAc,GAAG,IAAI,YAAY,CAAC,WAAW,CAAC,CAAC;IACrD,MAAM,aAAa,GAAG,IAAI,YAAY,CAAC,WAAW,CAAC,CAAC;IACpD,MAAM,YAAY,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;IACjD,MAAM,iBAAiB,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;IACtD,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3B,KAAK,IAAI,WAAW,GAAG,CAAC,EAAE,WAAW,GAAG,WAAW,EAAE,WAAW,EAAE,EAAE,CAAC;QACnE,YAAY,CAAC,WAAW,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,iBAAiB,CAAC;IAC3E,CAAC;IAED,OAAO;QACL,KAAK;QACL,aAAa,EAAE,IAAI;QACnB,WAAW;QACX,WAAW;QACX,cAAc;QACd,aAAa;QACb,YAAY;QACZ,iBAAiB;QACjB,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED,kGAAkG;AAClG,qGAAqG;AACrG,0FAA0F;AAC1F,MAAM,UAAU,2BAA2B,CACzC,QAAsC,EACtC,WAAmB;IAEnB,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACnD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,wBAAwB,CAAC,WAAW,CAAC,CAAC;IAEvE,MAAM,gBAAgB,GAAG,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IAC9C,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,wBAAwB,CAAC,WAAW,CAAC,CAAC;IAEtE,MAAM,qBAAqB,GAAG,QAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IACtE,IAAI,qBAAqB,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,gBAAgB,GAAG,KAAK,CAAC,WAAW,CAAC,qBAAqB,CAAC,CAAC;QAClE,IAAI,gBAAgB,KAAK,SAAS;YAAE,OAAO,wBAAwB,CAAC,WAAW,CAAC,CAAC;QACjF,OAAO;YACL,KAAK,EAAE,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC;YACxC,cAAc,EAAE,CAAC,CAAC;YAClB,WAAW;YACX,gBAAgB;YAChB,MAAM,EAAE,0BAA0B,CAAC,aAAa;YAChD,gBAAgB,EAAE,gBAAgB,CAAC,gBAAgB;YACnD,eAAe,EAAE,qBAAqB;SACvC,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO;YACL,KAAK,EAAE,CAAC;YACR,cAAc,EAAE,CAAC,CAAC;YAClB,WAAW;YACX,gBAAgB;YAChB,MAAM,EAAE,0BAA0B,CAAC,aAAa;YAChD,gBAAgB,EAAE,CAAC,CAAC;YACpB,eAAe,EAAE,CAAC,CAAC;SACpB,CAAC;IACJ,CAAC;IAED,IAAI,YAAY,GAA2C,IAAI,CAAC;IAChE,KAAK,IAAI,eAAe,GAAG,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,CAAC;QAC5F,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;QACtD,MAAM,cAAc,GAAG,sBAAsB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QACpE,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;YACxB,YAAY,KAAK;gBACf,KAAK,EAAE,CAAC;gBACR,cAAc;gBACd,WAAW;gBACX,gBAAgB;gBAChB,MAAM,EAAE,0BAA0B,CAAC,eAAe;gBAClD,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;gBAC7C,eAAe;aAChB,CAAC;YACF,SAAS;QACX,CAAC;QACD,MAAM,UAAU,GAAG,uBAAuB,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;QAC9E,IAAI,UAAU,KAAK,0BAA0B,CAAC,qBAAqB,EAAE,CAAC;YACpE,OAAO;gBACL,KAAK,EAAE,CAAC;gBACR,cAAc,EAAE,CAAC,CAAC;gBAClB,WAAW;gBACX,gBAAgB;gBAChB,MAAM,EAAE,0BAA0B,CAAC,qBAAqB;gBACxD,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;gBAC7C,eAAe;aAChB,CAAC;QACJ,CAAC;QACD,IAAI,UAAU,KAAK,0BAA0B,CAAC,eAAe,EAAE,CAAC;YAC9D,YAAY,KAAK;gBACf,KAAK,EAAE,CAAC;gBACR,cAAc,EAAE,CAAC,CAAC;gBAClB,WAAW;gBACX,gBAAgB;gBAChB,MAAM,EAAE,0BAA0B,CAAC,eAAe;gBAClD,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;gBAC7C,eAAe;aAChB,CAAC;YACF,SAAS;QACX,CAAC;QACD,OAAO;YACL,KAAK,EAAE,CAAC;YACR,cAAc,EAAE,CAAC,CAAC;YAClB,WAAW;YACX,gBAAgB;YAChB,MAAM,EAAE,0BAA0B,CAAC,KAAK;YACxC,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;YAC7C,eAAe;SAChB,CAAC;IACJ,CAAC;IAED,OAAO,YAA+C,CAAC;AACzD,CAAC;AAED,oGAAoG;AACpG,wGAAwG;AACxG,MAAM,UAAU,qBAAqB,CAAC,QAA4B,EAAE,UAAkB;IACpF,yBAAyB,CAAC,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7E,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;AACvC,CAAC;AAED,qGAAqG;AACrG,+EAA+E;AAC/E,MAAM,UAAU,uBAAuB,CAAC,KAA2B,EAAE,IAAY;IAC/E,KAAK,IAAI,UAAU,GAAG,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC;QACxE,IAAI,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,KAAK,IAAI;YAAE,OAAO,UAAU,CAAC;IAChE,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED,mGAAmG;AACnG,oGAAoG;AACpG,MAAM,UAAU,wBAAwB,CAAC,QAAsC,EAAE,WAAmB;IAClG,OAAO,WAAW,IAAI,CAAC,IAAI,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChH,CAAC;AAED,0FAA0F;AAC1F,MAAM,UAAU,wBAAwB,CAAC,QAAsC,EAAE,WAAmB;IAClG,OAAO,WAAW,IAAI,CAAC,IAAI,WAAW,GAAG,QAAQ,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAClH,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,yBAAyB,CAAC,QAA4B,EAAE,UAAkB,EAAE,KAAc;IACxG,yBAAyB,CAAC,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC7E,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,oGAAoG;AACpG,0BAA0B;AAC1B,MAAM,UAAU,wBAAwB,CAAC,QAA4B,EAAE,UAAkB,EAAE,KAAa;IACtG,yBAAyB,CAAC,QAAQ,EAAE,UAAU,EAAE,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAC5E,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC;AAC3C,CAAC;AAED,gGAAgG;AAChG,wGAAwG;AACxG,yGAAyG;AACzG,MAAM,UAAU,2BAA2B,CAAC,QAA4B,EAAE,WAAmB,EAAE,QAAgB;IAC7G,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC,IAAI,WAAW,IAAI,QAAQ,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC;QACvG,MAAM,IAAI,UAAU,CAAC,2BAA2B,WAAW,kBAAkB,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,UAAU,CAAC,4DAA4D,CAAC,CAAC;IACrF,CAAC;IACD,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC;AAClD,CAAC;AAED,SAAS,uBAAuB,CAAC,QAA4B,EAAE,WAAmB,EAAE,WAAmB;IACrG,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,gBAAgB,GAAG,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;IAC5D,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACpD,IAAI,WAAW,KAAK,SAAS;QAAE,MAAM,IAAI,UAAU,CAAC,qBAAqB,WAAW,8BAA8B,CAAC,CAAC;IACpH,QAAQ,CAAC,aAAa,CAAC,WAAW,CAAC,IAAI,WAAW,CAAC;IAEnD,IAAI,eAAe,GAAG,QAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAC9D,IAAI,UAAsD,CAAC;IAC3D,IAAI,eAAe,IAAI,CAAC,EAAE,CAAC;QACzB,UAAU,GAAG,WAAW,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;QACtD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,IAAI,UAAU,CAAC,qBAAqB,WAAW,mCAAmC,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC;SAAM,CAAC;QACN,eAAe,GAAG,uBAAuB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;QACjE,IAAI,eAAe,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACtC,UAAU,GAAG,WAAW,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;QACtD,QAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,GAAG,eAAe,CAAC;QAC1D,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACnH,MAAM,KAAK,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,WAAW,GAAG,UAAU,CAAC,CAAC;IAC/G,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,KAAK,CAAC;IAC1C,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAE5B,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,GAAG,UAAU,CAAC,gBAAgB,CAAC;IACjE,QAAQ,CAAC,iBAAiB,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACxC,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,yBAAyB,CAChC,QAAsC,EACtC,UAAkB,EAClB,YAA4E;IAE5E,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAChD,IAAI,KAAK,KAAK,SAAS;QAAE,MAAM,IAAI,UAAU,CAAC,0BAA0B,UAAU,kBAAkB,CAAC,CAAC;IACtG,IAAI,KAAK,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,oBAAoB,UAAU,OAAO,KAAK,CAAC,IAAI,SAAS,YAAY,EAAE,CAAC,CAAC;IAC9F,CAAC;AACH,CAAC;AAED,SAAS,uBAAuB,CAAC,QAA4B;IAC3D,KAAK,IAAI,UAAU,GAAG,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC;QACjF,IAAI,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,KAAK,mBAAmB,CAAC,OAAO;YAAE,QAAQ,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACnH,CAAC;AACH,CAAC;AAED,SAAS,0BAA0B,CAAC,KAAa,EAAE,SAAwC;IACzF,QAAQ,SAAS,CAAC,UAAU,EAAE,CAAC;QAC7B,KAAK,oBAAoB,CAAC,KAAK;YAC7B,OAAO,KAAK,KAAK,SAAS,CAAC,KAAK,CAAC;QACnC,KAAK,oBAAoB,CAAC,WAAW;YACnC,OAAO,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;QACjC,KAAK,oBAAoB,CAAC,kBAAkB;YAC1C,OAAO,KAAK,IAAI,SAAS,CAAC,KAAK,CAAC;QAClC,KAAK,oBAAoB,CAAC,QAAQ;YAChC,OAAO,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC;QACjC,KAAK,oBAAoB,CAAC,eAAe;YACvC,OAAO,KAAK,IAAI,SAAS,CAAC,KAAK,CAAC;QAClC,KAAK,oBAAoB,CAAC,QAAQ;YAChC,OAAO,KAAK,KAAK,SAAS,CAAC,KAAK,CAAC;IACrC,CAAC;AACH,CAAC;AAED,SAAS,sBAAsB,CAC7B,QAAsC,EACtC,UAA0C;IAE1C,KAAK,IAAI,cAAc,GAAG,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,CAAC;QAC7F,MAAM,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAC1D,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,cAAc,CAAC;QAC/C,MAAM,UAAU,GAAG,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;QAC9D,MAAM,GAAG,GACP,KAAK,CAAC,IAAI,KAAK,mBAAmB,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,CAAC,CAAC,0BAA0B,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;QACpH,IAAI,CAAC,GAAG;YAAE,OAAO,cAAc,CAAC;IAClC,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED,SAAS,uBAAuB,CAAC,QAAsC,EAAE,WAAmB;IAC1F,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACnD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC,CAAC;IAChE,KAAK,IAAI,eAAe,GAAG,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,CAAC;QAC5F,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;QACtD,IAAI,sBAAsB,CAAC,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC;YAAE,SAAS;QAChE,MAAM,UAAU,GAAG,uBAAuB,CAAC,QAAQ,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;QAC9E,IAAI,UAAU,KAAK,0BAA0B,CAAC,eAAe;YAAE,SAAS;QACxE,IAAI,UAAU,KAAK,0BAA0B,CAAC,qBAAqB,EAAE,CAAC;YACpE,QAAQ,CAAC,aAAa,EAAE,CAAC,QAAQ,EAAE;gBACjC,KAAK,EAAE,CAAC;gBACR,cAAc,EAAE,CAAC,CAAC;gBAClB,WAAW;gBACX,gBAAgB,EAAE,QAAQ,CAAC,YAAY,CAAC,WAAW,CAAC;gBACpD,MAAM,EAAE,0BAA0B,CAAC,qBAAqB;gBACxD,gBAAgB,EAAE,UAAU,CAAC,gBAAgB;gBAC7C,eAAe;aAChB,CAAC,CAAC;QACL,CAAC;QACD,OAAO,eAAe,CAAC;IACzB,CAAC;IACD,OAAO,CAAC,CAAC,CAAC;AACZ,CAAC;AAED,SAAS,uBAAuB,CAC9B,QAAsC,EACtC,WAAmB,EACnB,UAA0C;IAK1C,IAAI,UAAU,CAAC,aAAa,GAAG,CAAC;QAAE,OAAO,0BAA0B,CAAC,KAAK,CAAC;IAC1E,MAAM,QAAQ,GAAG,QAAQ,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IACtD,IAAI,QAAQ,IAAI,CAAC;QAAE,OAAO,0BAA0B,CAAC,qBAAqB,CAAC;IAC3E,OAAO,QAAQ,CAAC,aAAa,CAAC,WAAW,CAAC,GAAG,QAAQ,IAAI,UAAU,CAAC,aAAa;QAC/E,CAAC,CAAC,0BAA0B,CAAC,KAAK;QAClC,CAAC,CAAC,0BAA0B,CAAC,eAAe,CAAC;AACjD,CAAC;AAED,SAAS,wBAAwB,CAAC,WAAmB;IACnD,OAAO;QACL,KAAK,EAAE,CAAC,CAAC;QACT,cAAc,EAAE,CAAC,CAAC;QAClB,WAAW;QACX,gBAAgB,EAAE,CAAC,CAAC;QACpB,MAAM,EAAE,0BAA0B,CAAC,aAAa;QAChD,gBAAgB,EAAE,CAAC,CAAC;QACpB,eAAe,EAAE,CAAC,CAAC;KACpB,CAAC;AACJ,CAAC;AAED,SAAS,kBAAkB,CAAC,KAA2B;IACrD,KAAK,IAAI,UAAU,GAAG,CAAC,EAAE,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC;QACxE,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC;QAC3C,IACE,IAAI,KAAK,mBAAmB,CAAC,OAAO;YACpC,IAAI,KAAK,mBAAmB,CAAC,MAAM;YACnC,IAAI,KAAK,mBAAmB,CAAC,OAAO,EACpC,CAAC;YACD,MAAM,IAAI,SAAS,CAAC,oBAAoB,UAAU,qBAAqB,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzF,CAAC;IACH,CAAC;IAED,KAAK,IAAI,WAAW,GAAG,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,CAAC;QAC5E,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QAC1C,IAAI,MAAM,CAAC,iBAAiB,GAAG,CAAC,IAAI,MAAM,CAAC,iBAAiB,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACrF,MAAM,IAAI,UAAU,CAAC,qBAAqB,WAAW,mCAAmC,CAAC,CAAC;QAC5F,CAAC;QACD,KAAK,IAAI,UAAU,GAAG,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC;YACzE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACxC,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9D,MAAM,IAAI,SAAS,CAAC,qBAAqB,WAAW,UAAU,UAAU,sBAAsB,CAAC,CAAC;YAClG,CAAC;YACD,KAAK,IAAI,eAAe,GAAG,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC,WAAW,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,CAAC;gBAC5F,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,CAAC,eAAe,CAAC,CAAC;gBACtD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;oBACzE,MAAM,IAAI,UAAU,CAClB,qBAAqB,WAAW,UAAU,UAAU,eAAe,eAAe,0BAA0B,CAC7G,CAAC;gBACJ,CAAC;gBACD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,aAAa,CAAC,IAAI,UAAU,CAAC,aAAa,GAAG,CAAC,CAAC,EAAE,CAAC;oBAChF,MAAM,IAAI,UAAU,CAClB,qBAAqB,WAAW,UAAU,UAAU,eAAe,eAAe,2BAA2B,CAC9G,CAAC;gBACJ,CAAC;gBACD,IAAI,UAAU,CAAC,gBAAgB,GAAG,CAAC,IAAI,UAAU,CAAC,gBAAgB,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;oBAC3F,MAAM,IAAI,UAAU,CAClB,qBAAqB,WAAW,UAAU,UAAU,eAAe,eAAe,wBAAwB,CAC3G,CAAC;gBACJ,CAAC;gBACD,KAAK,IAAI,cAAc,GAAG,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC,UAAU,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,CAAC;oBAC7F,MAAM,SAAS,GAAG,UAAU,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;oBACxD,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC;oBACxC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,IAAI,UAAU,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;wBACzF,MAAM,IAAI,UAAU,CAClB,qBAAqB,WAAW,UAAU,UAAU,eAAe,eAAe,uBAAuB,CAC1G,CAAC;oBACJ,CAAC;oBACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;wBACxE,MAAM,IAAI,SAAS,CACjB,qBAAqB,WAAW,UAAU,UAAU,eAAe,eAAe,4BAA4B,CAC/G,CAAC;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/statechartSignals.d.ts

@@ -0,0 +1,4 @@
+import type { StatechartInstance, StatechartSignals } from '@flighthq/types/contract';
+export declare function enableStatechartSignals(instance: StatechartInstance): StatechartSignals;
+export declare function getStatechartSignals(instance: Readonly<StatechartInstance>): StatechartSignals | null;
+//# sourceMappingURL=statechartSignals.d.ts.map

package/dist/statechartSignals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statechartSignals.d.ts","sourceRoot":"","sources":["../src/statechartSignals.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAKtF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,iBAAiB,CAIvF;AAID,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,CAAC,GAAG,iBAAiB,GAAG,IAAI,CAErG"}

package/dist/statechartSignals.js

@@ -0,0 +1,15 @@
+import { createSignal } from '@flighthq/signals/contract';
+// Allocate the optional observer group on first use. The nullable slot lives on the mutable instance,
+// never on the immutable chart, so authored/imported state remains closure-free and serializable. This
+// module is separately tree-shakeable: count/read users do not pay for the signals runtime.
+export function enableStatechartSignals(instance) {
+    return (instance.signals ??= {
+        onStateChange: createSignal(),
+    });
+}
+// Read the optional observer group without allocating it. Returns null until enableStatechartSignals
+// has been called for this actor.
+export function getStatechartSignals(instance) {
+    return instance.signals;
+}
+//# sourceMappingURL=statechartSignals.js.map

package/dist/statechartSignals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statechartSignals.js","sourceRoot":"","sources":["../src/statechartSignals.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAG1D,sGAAsG;AACtG,uGAAuG;AACvG,4FAA4F;AAC5F,MAAM,UAAU,uBAAuB,CAAC,QAA4B;IAClE,OAAO,CAAC,QAAQ,CAAC,OAAO,KAAK;QAC3B,aAAa,EAAE,YAAY,EAAE;KAC9B,CAAC,CAAC;AACL,CAAC;AAED,qGAAqG;AACrG,kCAAkC;AAClC,MAAM,UAAU,oBAAoB,CAAC,QAAsC;IACzE,OAAO,QAAQ,CAAC,OAAO,CAAC;AAC1B,CAAC"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@flighthq/statechart",
+  "version": "0.3.0-next.1728.26853f6",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/statechart"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/log": "0.3.0-next.1728.26853f6",
+    "@flighthq/signals": "0.3.0-next.1728.26853f6",
+    "@flighthq/types": "0.3.0-next.1728.26853f6"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Plain-data concurrent statecharts with typed inputs, guarded transitions, and reported blend progress",
+  "sideEffects": false
+}

package/src/enableStatechartGuards.test.ts

@@ -0,0 +1,96 @@
+import { addLogSink, createMemoryLogSink, getMemoryLogSinkEntries, removeLogSink } from '@flighthq/log/contract';
+import { StatechartAtomicStateKind, StatechartTransitionStatus } from '@flighthq/types/contract';
+import type { LogEntry, Statechart } from '@flighthq/types/contract';
+
+import { areStatechartGuardsEnabled, disableStatechartGuards, enableStatechartGuards } from './enableStatechartGuards';
+import { advanceStatechartInstance, createStatechartInstance, setStatechartRegionDuration } from './statechart';
+
+describe('areStatechartGuardsEnabled', () => {
+  it('reports guard state per actor', () => {
+    const guarded = createStatechartInstance(createExitTimeChart());
+    const unguarded = createStatechartInstance(createExitTimeChart());
+    enableStatechartGuards(guarded);
+    expect(areStatechartGuardsEnabled(guarded)).toBe(true);
+    expect(areStatechartGuardsEnabled(unguarded)).toBe(false);
+  });
+});
+
+describe('disableStatechartGuards', () => {
+  it('restores silent coercion without changing transition behavior', () => {
+    const instance = createStatechartInstance(createExitTimeChart());
+    enableStatechartGuards(instance);
+    disableStatechartGuards(instance);
+    const entries = captureLog(() => {
+      expect(advanceStatechartInstance(instance, 0)).toBe(1);
+    });
+    expect(entries).toEqual([]);
+  });
+});
+
+describe('enableStatechartGuards', () => {
+  it('warns once and names the duration setter while preserving no-requirement coercion', () => {
+    const instance = createStatechartInstance(createExitTimeChart());
+    enableStatechartGuards(instance);
+    const entries = captureLog(() => {
+      expect(advanceStatechartInstance(instance, 0)).toBe(1);
+    });
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({ channel: 'statechart', level: 2 });
+    expect(entries[0].data).toMatchObject({
+      exitTimeRatio: 0.5,
+      regionDuration: 0,
+      regionIndex: 0,
+      status: StatechartTransitionStatus.MissingRegionDuration,
+      transitionIndex: 0,
+    });
+    expect(String((entries[0].data as Record<string, unknown>).message)).toContain('setStatechartRegionDuration');
+  });
+
+  it('stays silent when a positive duration makes the exit-time ratio well-defined', () => {
+    const instance = createStatechartInstance(createExitTimeChart());
+    enableStatechartGuards(instance);
+    setStatechartRegionDuration(instance, 0, 100);
+    const entries = captureLog(() => {
+      expect(advanceStatechartInstance(instance, 49)).toBe(0);
+      expect(advanceStatechartInstance(instance, 1)).toBe(1);
+    });
+    expect(entries).toEqual([]);
+  });
+
+  it('keeps the production-default coercion silent when guards were never enabled', () => {
+    const instance = createStatechartInstance(createExitTimeChart());
+    const entries = captureLog(() => {
+      expect(advanceStatechartInstance(instance, 0)).toBe(1);
+    });
+    expect(entries).toEqual([]);
+  });
+});
+
+function captureLog(run: () => void): readonly LogEntry[] {
+  const sink = createMemoryLogSink(8);
+  addLogSink(sink.sink);
+  try {
+    run();
+    return getMemoryLogSinkEntries(sink);
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+function createExitTimeChart(): Statechart {
+  return {
+    inputs: [],
+    regions: [
+      {
+        initialStateIndex: 0,
+        states: [
+          {
+            kind: StatechartAtomicStateKind,
+            transitions: [{ conditions: [], durationMs: 0, exitTimeRatio: 0.5, targetStateIndex: 1 }],
+          },
+          { kind: StatechartAtomicStateKind, transitions: [] },
+        ],
+      },
+    ],
+  };
+}

package/src/statechart.test.ts

@@ -0,0 +1,435 @@
+import {
+  StatechartAtomicStateKind,
+  StatechartComparison,
+  StatechartInputKind,
+  StatechartNestedStateKind,
+  StatechartTransitionStatus,
+} from '@flighthq/types/contract';
+import type { Statechart, StatechartCondition, StatechartTransition } from '@flighthq/types/contract';
+
+import {
+  advanceStatechartInstance,
+  createStatechartInstance,
+  explainStatechartTransition,
+  fireStatechartTrigger,
+  getStatechartInputIndex,
+  getStatechartRegionBlend,
+  getStatechartRegionState,
+  setStatechartBooleanInput,
+  setStatechartNumberInput,
+  setStatechartRegionDuration,
+} from './statechart';
+
+describe('advanceStatechartInstance', () => {
+  it('advances every concurrent region before clearing a shared trigger', () => {
+    const chart = createTwoRegionTriggerChart();
+    const instance = createStatechartInstance(chart);
+
+    fireStatechartTrigger(instance, 0);
+    expect(advanceStatechartInstance(instance, 0)).toBe(2);
+    expect([...instance.regionStates]).toEqual([1, 1]);
+    expect(instance.inputValues[0]).toBe(0);
+  });
+
+  it('requires all data-only conditions and selects the first eligible transition', () => {
+    const chart: Statechart = {
+      inputs: [
+        { initialValue: 0, kind: StatechartInputKind.Boolean, name: 'armed' },
+        { initialValue: 2, kind: StatechartInputKind.Number, name: 'speed' },
+      ],
+      regions: [
+        {
+          initialStateIndex: 0,
+          states: [
+            {
+              kind: StatechartAtomicStateKind,
+              transitions: [
+                transition(1, [condition(0, StatechartComparison.Equal, 1)]),
+                transition(2, [
+                  condition(0, StatechartComparison.Equal, 0),
+                  condition(1, StatechartComparison.GreaterThan, 4),
+                ]),
+                transition(1, [
+                  condition(0, StatechartComparison.Equal, 0),
+                  condition(1, StatechartComparison.LessThanOrEqual, 2),
+                ]),
+              ],
+            },
+            { kind: StatechartAtomicStateKind, transitions: [] },
+            { kind: StatechartAtomicStateKind, transitions: [] },
+          ],
+        },
+      ],
+    };
+    const instance = createStatechartInstance(chart);
+
+    expect(advanceStatechartInstance(instance, 0)).toBe(1);
+    expect(instance.regionStates[0]).toBe(1);
+  });
+
+  it.each([
+    [StatechartComparison.Equal, 3, 3, true],
+    [StatechartComparison.GreaterThan, 3, 2, true],
+    [StatechartComparison.GreaterThanOrEqual, 3, 3, true],
+    [StatechartComparison.LessThan, 3, 4, true],
+    [StatechartComparison.LessThanOrEqual, 3, 3, true],
+    [StatechartComparison.NotEqual, 3, 4, true],
+  ])('evaluates the %s numeric comparison', (comparison, inputValue, expectedValue, expected) => {
+    const chart = createSingleTransitionChart(
+      [{ initialValue: inputValue, kind: StatechartInputKind.Number }],
+      [condition(0, comparison, expectedValue)],
+    );
+    expect(advanceStatechartInstance(createStatechartInstance(chart), 0) === 1).toBe(expected);
+  });
+
+  it('reports blend progress without performing composition and changes state at completion', () => {
+    const chart = createSingleTransitionChart([], [], { durationMs: 100 });
+    const instance = createStatechartInstance(chart);
+
+    expect(advanceStatechartInstance(instance, 40)).toBe(0);
+    expect(instance.regionStates[0]).toBe(0);
+    expect(getStatechartRegionBlend(instance, 0)).toBeCloseTo(0.4);
+    expect(advanceStatechartInstance(instance, 60)).toBe(1);
+    expect(instance.regionStates[0]).toBe(1);
+    expect(getStatechartRegionBlend(instance, 0)).toBe(0);
+  });
+
+  it('accumulates elapsed time and evaluates exitTimeRatio against the caller-supplied duration', () => {
+    const chart = createSingleTransitionChart([], [], { exitTimeRatio: 0.5 });
+    const instance = createStatechartInstance(chart);
+    setStatechartRegionDuration(instance, 0, 100);
+
+    expect(advanceStatechartInstance(instance, 49)).toBe(0);
+    expect(instance.regionElapsed[0]).toBe(49);
+    expect(advanceStatechartInstance(instance, 1)).toBe(1);
+    expect(instance.regionStates[0]).toBe(1);
+    expect(instance.regionElapsed[0]).toBe(0);
+    expect(instance.regionDuration[0]).toBe(0);
+  });
+
+  it('changes a region at most once per call even when the target has an immediate transition', () => {
+    const chart: Statechart = {
+      inputs: [],
+      regions: [
+        {
+          initialStateIndex: 0,
+          states: [
+            { kind: StatechartAtomicStateKind, transitions: [transition(1)] },
+            { kind: StatechartAtomicStateKind, transitions: [transition(2)] },
+            { kind: StatechartAtomicStateKind, transitions: [] },
+          ],
+        },
+      ],
+    };
+    const instance = createStatechartInstance(chart);
+
+    expect(advanceStatechartInstance(instance, 0)).toBe(1);
+    expect(instance.regionStates[0]).toBe(1);
+    expect(advanceStatechartInstance(instance, 0)).toBe(1);
+    expect(instance.regionStates[0]).toBe(2);
+  });
+
+  it('treats non-positive and non-finite time as no blend progress', () => {
+    const chart = createSingleTransitionChart([], [], { durationMs: 100 });
+    const instance = createStatechartInstance(chart);
+
+    expect(advanceStatechartInstance(instance, -1)).toBe(0);
+    expect(advanceStatechartInstance(instance, Number.NaN)).toBe(0);
+    expect(instance.regionBlend[0]).toBe(0);
+  });
+});
+
+describe('createStatechartInstance', () => {
+  it('creates independent typed-array actor state while retaining the immutable chart', () => {
+    const chart: Statechart = {
+      inputs: [
+        { initialValue: -2, kind: StatechartInputKind.Boolean },
+        { initialValue: 3.5, kind: StatechartInputKind.Number },
+        { initialValue: 0, kind: StatechartInputKind.Trigger },
+      ],
+      name: 'shared',
+      regions: [
+        {
+          initialStateIndex: 1,
+          states: [
+            { kind: StatechartNestedStateKind, transitions: [] },
+            { kind: 'acme.CustomState', transitions: [] },
+          ],
+        },
+      ],
+    };
+
+    const first = createStatechartInstance(chart);
+    const second = createStatechartInstance(chart);
+    expect(first.chart).toBe(chart);
+    expect(first.chart).toBe(second.chart);
+    expect(first.inputValues).toBeInstanceOf(Float64Array);
+    expect([...first.inputValues]).toEqual([1, 3.5, 0]);
+    expect(first.regionBlend).toBeInstanceOf(Float32Array);
+    expect(first.regionDuration).toBeInstanceOf(Float64Array);
+    expect(first.regionElapsed).toBeInstanceOf(Float64Array);
+    expect(first.regionStates).toBeInstanceOf(Int32Array);
+    expect(first.regionTransitions).toBeInstanceOf(Int32Array);
+    expect([...first.regionStates]).toEqual([1]);
+    expect([...first.regionTransitions]).toEqual([-1]);
+    expect(first.durationGuard).toBeNull();
+    expect(first.signals).toBeNull();
+
+    first.inputValues[1] = 9;
+    expect(second.inputValues[1]).toBe(3.5);
+  });
+
+  it('rejects malformed authored indices as programmer errors', () => {
+    const chart: Statechart = {
+      inputs: [],
+      regions: [{ initialStateIndex: 1, states: [{ kind: StatechartAtomicStateKind, transitions: [] }] }],
+    };
+    expect(() => createStatechartInstance(chart)).toThrow(RangeError);
+  });
+
+  it('accepts nested and vendor-prefixed state kinds without closed dispatch', () => {
+    const chart: Statechart = {
+      inputs: [],
+      regions: [
+        {
+          initialStateIndex: 0,
+          states: [
+            { kind: StatechartNestedStateKind, transitions: [] },
+            { kind: 'vendor.Special', transitions: [] },
+          ],
+        },
+      ],
+    };
+    expect(() => createStatechartInstance(chart)).not.toThrow();
+  });
+});
+
+describe('explainStatechartTransition', () => {
+  it('returns an invalid-region diagnostic for the silent getter sentinel', () => {
+    const explanation = explainStatechartTransition(createStatechartInstance(createEmptyChart()), 4);
+    expect(explanation).toEqual({
+      blend: -1,
+      conditionIndex: -1,
+      regionIndex: 4,
+      sourceStateIndex: -1,
+      status: StatechartTransitionStatus.InvalidRegion,
+      targetStateIndex: -1,
+      transitionIndex: -1,
+    });
+  });
+
+  it('reports a state with no transitions', () => {
+    const explanation = explainStatechartTransition(createStatechartInstance(createEmptyChart()), 0);
+    expect(explanation.status).toBe(StatechartTransitionStatus.NoTransitions);
+    expect(explanation.transitionIndex).toBe(-1);
+  });
+
+  it('identifies the first unmet condition', () => {
+    const chart = createSingleTransitionChart(
+      [{ initialValue: 0, kind: StatechartInputKind.Number }],
+      [condition(0, StatechartComparison.GreaterThan, 2)],
+    );
+    const explanation = explainStatechartTransition(createStatechartInstance(chart), 0);
+    expect(explanation.status).toBe(StatechartTransitionStatus.ConditionsUnmet);
+    expect(explanation.conditionIndex).toBe(0);
+    expect(explanation.targetStateIndex).toBe(1);
+  });
+
+  it('reports ready and transitioning states without mutation', () => {
+    const chart = createSingleTransitionChart([], [], { durationMs: 100 });
+    const instance = createStatechartInstance(chart);
+    expect(explainStatechartTransition(instance, 0).status).toBe(StatechartTransitionStatus.Ready);
+    advanceStatechartInstance(instance, 25);
+    const explanation = explainStatechartTransition(instance, 0);
+    expect(explanation.status).toBe(StatechartTransitionStatus.Transitioning);
+    expect(explanation.blend).toBeCloseTo(0.25);
+    expect(explanation.transitionIndex).toBe(0);
+  });
+
+  it('reports a satisfied guard waiting on exit time', () => {
+    const chart = createSingleTransitionChart([], [], { exitTimeRatio: 0.5 });
+    const instance = createStatechartInstance(chart);
+    setStatechartRegionDuration(instance, 0, 100);
+    const explanation = explainStatechartTransition(instance, 0);
+    expect(explanation.status).toBe(StatechartTransitionStatus.ExitTimePending);
+    expect(explanation.conditionIndex).toBe(-1);
+  });
+
+  it('reports a missing duration that runtime coerces to no exit-time requirement', () => {
+    const chart = createSingleTransitionChart([], [], { exitTimeRatio: 0.5 });
+    const explanation = explainStatechartTransition(createStatechartInstance(chart), 0);
+    expect(explanation.status).toBe(StatechartTransitionStatus.MissingRegionDuration);
+    expect(explanation.transitionIndex).toBe(0);
+  });
+});
+
+describe('fireStatechartTrigger', () => {
+  it('latches a trigger until all regions see the next advance and ignores condition value', () => {
+    const instance = createStatechartInstance(createTwoRegionTriggerChart());
+    fireStatechartTrigger(instance, 0);
+    expect(instance.inputValues[0]).toBe(1);
+    expect(advanceStatechartInstance(instance, 0)).toBe(2);
+    expect(instance.inputValues[0]).toBe(0);
+  });
+
+  it('throws for an invalid index or non-trigger input', () => {
+    const instance = createStatechartInstance(
+      createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Number }]),
+    );
+    expect(() => fireStatechartTrigger(instance, -1)).toThrow(RangeError);
+    expect(() => fireStatechartTrigger(instance, 0)).toThrow(TypeError);
+  });
+});
+
+describe('getStatechartInputIndex', () => {
+  it('returns the first matching input index and -1 when absent', () => {
+    const chart: Statechart = {
+      inputs: [
+        { initialValue: 0, kind: StatechartInputKind.Number, name: 'speed' },
+        { initialValue: 1, kind: StatechartInputKind.Number, name: 'speed' },
+      ],
+      regions: [],
+    };
+    expect(getStatechartInputIndex(chart, 'speed')).toBe(0);
+    expect(getStatechartInputIndex(chart, 'missing')).toBe(-1);
+  });
+});
+
+describe('getStatechartRegionBlend', () => {
+  it('returns a region blend and -1 for invalid regions', () => {
+    const instance = createStatechartInstance(createEmptyChart());
+    instance.regionBlend[0] = 0.4;
+    expect(getStatechartRegionBlend(instance, 0)).toBeCloseTo(0.4);
+    expect(getStatechartRegionBlend(instance, -1)).toBe(-1);
+    expect(getStatechartRegionBlend(instance, 1)).toBe(-1);
+  });
+});
+
+describe('getStatechartRegionState', () => {
+  it('returns a region state and -1 for invalid regions', () => {
+    const instance = createStatechartInstance(createEmptyChart());
+    expect(getStatechartRegionState(instance, 0)).toBe(0);
+    expect(getStatechartRegionState(instance, -1)).toBe(-1);
+    expect(getStatechartRegionState(instance, 1)).toBe(-1);
+  });
+});
+
+describe('setStatechartBooleanInput', () => {
+  it('writes the Boolean input vocabulary as numeric 0/1', () => {
+    const instance = createStatechartInstance(
+      createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Boolean }]),
+    );
+    setStatechartBooleanInput(instance, 0, true);
+    expect(instance.inputValues[0]).toBe(1);
+    setStatechartBooleanInput(instance, 0, false);
+    expect(instance.inputValues[0]).toBe(0);
+  });
+
+  it('throws for an invalid index or non-Boolean input', () => {
+    const instance = createStatechartInstance(
+      createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Number }]),
+    );
+    expect(() => setStatechartBooleanInput(instance, 1, true)).toThrow(RangeError);
+    expect(() => setStatechartBooleanInput(instance, 0, true)).toThrow(TypeError);
+  });
+});
+
+describe('setStatechartNumberInput', () => {
+  it('writes an exact numeric value', () => {
+    const instance = createStatechartInstance(
+      createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Number }]),
+    );
+    setStatechartNumberInput(instance, 0, -3.25);
+    expect(instance.inputValues[0]).toBe(-3.25);
+  });
+
+  it('throws for an invalid index or non-Number input', () => {
+    const instance = createStatechartInstance(
+      createSingleTransitionChart([{ initialValue: 0, kind: StatechartInputKind.Boolean }]),
+    );
+    expect(() => setStatechartNumberInput(instance, 1, 2)).toThrow(RangeError);
+    expect(() => setStatechartNumberInput(instance, 0, 2)).toThrow(TypeError);
+  });
+});
+
+describe('setStatechartRegionDuration', () => {
+  it('sets the plain per-region exit-time denominator', () => {
+    const instance = createStatechartInstance(createEmptyChart());
+    setStatechartRegionDuration(instance, 0, 250);
+    expect(instance.regionDuration[0]).toBe(250);
+  });
+
+  it('accepts zero as an explicit unavailable duration', () => {
+    const instance = createStatechartInstance(createEmptyChart());
+    setStatechartRegionDuration(instance, 0, 0);
+    expect(instance.regionDuration[0]).toBe(0);
+  });
+
+  it('throws for an invalid region or invalid duration', () => {
+    const instance = createStatechartInstance(createEmptyChart());
+    expect(() => setStatechartRegionDuration(instance, 1, 1)).toThrow(RangeError);
+    expect(() => setStatechartRegionDuration(instance, 0, -1)).toThrow(RangeError);
+    expect(() => setStatechartRegionDuration(instance, 0, Number.NaN)).toThrow(RangeError);
+  });
+});
+
+function condition(inputIndex: number, comparison: StatechartComparison, value: number): StatechartCondition {
+  return { comparison, inputIndex, value };
+}
+
+function createEmptyChart(): Statechart {
+  return {
+    inputs: [],
+    regions: [{ initialStateIndex: 0, states: [{ kind: StatechartAtomicStateKind, transitions: [] }] }],
+  };
+}
+
+function createSingleTransitionChart(
+  inputs: Statechart['inputs'],
+  conditions: readonly StatechartCondition[] = [],
+  options: Partial<Pick<StatechartTransition, 'durationMs' | 'exitTimeRatio'>> = {},
+): Statechart {
+  return {
+    inputs,
+    regions: [
+      {
+        initialStateIndex: 0,
+        states: [
+          {
+            kind: StatechartAtomicStateKind,
+            transitions: [transition(1, conditions, options)],
+          },
+          { kind: StatechartAtomicStateKind, transitions: [] },
+        ],
+      },
+    ],
+  };
+}
+
+function createTwoRegionTriggerChart(): Statechart {
+  const triggerTransition = transition(1, [condition(0, StatechartComparison.GreaterThan, 999)]);
+  const region = () => ({
+    initialStateIndex: 0,
+    states: [
+      { kind: StatechartAtomicStateKind, transitions: [triggerTransition] },
+      { kind: StatechartAtomicStateKind, transitions: [] },
+    ],
+  });
+  return {
+    inputs: [{ initialValue: 0, kind: StatechartInputKind.Trigger, name: 'go' }],
+    regions: [region(), region()],
+  };
+}
+
+function transition(
+  targetStateIndex: number,
+  conditions: readonly StatechartCondition[] = [],
+  options: Partial<Pick<StatechartTransition, 'durationMs' | 'exitTimeRatio'>> = {},
+): StatechartTransition {
+  return {
+    conditions,
+    durationMs: options.durationMs ?? 0,
+    exitTimeRatio: options.exitTimeRatio ?? -1,
+    targetStateIndex,
+  };
+}

package/src/statechartSignals.test.ts

@@ -0,0 +1,96 @@
+import { connectSignal } from '@flighthq/signals/contract';
+import { StatechartAtomicStateKind } from '@flighthq/types/contract';
+import type { Statechart } from '@flighthq/types/contract';
+
+import {
+  advanceStatechartInstance,
+  createStatechartInstance,
+  fireStatechartTrigger,
+  setStatechartRegionDuration,
+} from './statechart';
+import { enableStatechartSignals, getStatechartSignals } from './statechartSignals';
+
+describe('enableStatechartSignals', () => {
+  it('lazily attaches one standard signal group to the mutable instance', () => {
+    const instance = createStatechartInstance(createImmediateChart());
+    const first = enableStatechartSignals(instance);
+    const second = enableStatechartSignals(instance);
+    expect(first).toBe(second);
+    expect(instance.signals).toBe(first);
+    expect(first.onStateChange.data).toBeNull();
+  });
+
+  it('observes completed entry and exit without putting a closure on authored state data', () => {
+    const chart = createImmediateChart();
+    const instance = createStatechartInstance(chart);
+    const calls: number[][] = [];
+    connectSignal(enableStatechartSignals(instance).onStateChange, (regionIndex, previousState, state) => {
+      calls.push([regionIndex, previousState, state]);
+    });
+
+    expect(JSON.stringify(chart)).not.toContain('onEnter');
+    advanceStatechartInstance(instance, 0);
+    expect(calls).toEqual([[0, 0, 1]]);
+  });
+
+  it('emits after trigger cleanup so a listener can latch an edge for the next pass', () => {
+    const chart: Statechart = {
+      inputs: [{ initialValue: 0, kind: 'Trigger' }],
+      regions: [
+        {
+          initialStateIndex: 0,
+          states: [
+            {
+              kind: StatechartAtomicStateKind,
+              transitions: [{ conditions: [], durationMs: 0, exitTimeRatio: -1, targetStateIndex: 1 }],
+            },
+            { kind: StatechartAtomicStateKind, transitions: [] },
+          ],
+        },
+      ],
+    };
+    const instance = createStatechartInstance(chart);
+    connectSignal(enableStatechartSignals(instance).onStateChange, () => {
+      fireStatechartTrigger(instance, 0);
+    });
+    advanceStatechartInstance(instance, 0);
+    expect(instance.inputValues[0]).toBe(1);
+  });
+
+  it('lets composition supply the entered state duration after core resets the old one', () => {
+    const instance = createStatechartInstance(createImmediateChart());
+    setStatechartRegionDuration(instance, 0, 100);
+    connectSignal(enableStatechartSignals(instance).onStateChange, (regionIndex) => {
+      setStatechartRegionDuration(instance, regionIndex, 250);
+    });
+    advanceStatechartInstance(instance, 0);
+    expect(instance.regionDuration[0]).toBe(250);
+  });
+});
+
+describe('getStatechartSignals', () => {
+  it('returns null before enablement and the group afterward', () => {
+    const instance = createStatechartInstance(createImmediateChart());
+    expect(getStatechartSignals(instance)).toBeNull();
+    const signals = enableStatechartSignals(instance);
+    expect(getStatechartSignals(instance)).toBe(signals);
+  });
+});
+
+function createImmediateChart(): Statechart {
+  return {
+    inputs: [],
+    regions: [
+      {
+        initialStateIndex: 0,
+        states: [
+          {
+            kind: StatechartAtomicStateKind,
+            transitions: [{ conditions: [], durationMs: 0, exitTimeRatio: -1, targetStateIndex: 1 }],
+          },
+          { kind: StatechartAtomicStateKind, transitions: [] },
+        ],
+      },
+    ],
+  };
+}