@flighthq/flow 0.1.0

package/dist/clearFlowStack.d.ts

@@ -0,0 +1,3 @@
+import type { FlowStack } from '@flighthq/types';
+export declare function clearFlowStack(stack: FlowStack): void;
+//# sourceMappingURL=clearFlowStack.d.ts.map

package/dist/clearFlowStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clearFlowStack.d.ts","sourceRoot":"","sources":["../src/clearFlowStack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAKjD,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAMrD"}

package/dist/clearFlowStack.js

@@ -0,0 +1,11 @@
+// Empty the stack, exiting every state top-to-bottom (`onExit` on the active top first, down to the
+// bottom) so each unwinds in reverse of the order it entered. No `onPause`/`onResume` fire — the
+// whole stack is being torn down, not layered. After this the stack has depth 0.
+export function clearFlowStack(stack) {
+    const states = stack.states;
+    for (let i = states.length - 1; i >= 0; i--) {
+        states[i].onExit?.();
+    }
+    states.length = 0;
+}
+//# sourceMappingURL=clearFlowStack.js.map

package/dist/clearFlowStack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clearFlowStack.js","sourceRoot":"","sources":["../src/clearFlowStack.ts"],"names":[],"mappings":"AAEA,oGAAoG;AACpG,iGAAiG;AACjG,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,KAAgB;IAC7C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;IACvB,CAAC;IACD,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;AACpB,CAAC"}

package/dist/createFlowStack.d.ts

@@ -0,0 +1,3 @@
+import type { FlowStack } from '@flighthq/types';
+export declare function createFlowStack(): FlowStack;
+//# sourceMappingURL=createFlowStack.d.ts.map

package/dist/createFlowStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFlowStack.d.ts","sourceRoot":"","sources":["../src/createFlowStack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAIjD,wBAAgB,eAAe,IAAI,SAAS,CAE3C"}

package/dist/createFlowStack.js

@@ -0,0 +1,6 @@
+// Allocate an empty flow-state stack. The only allocating function; every other stack function reads
+// or mutates an existing stack in place. Push states onto it to drive the enter/pause lifecycle.
+export function createFlowStack() {
+    return { states: [] };
+}
+//# sourceMappingURL=createFlowStack.js.map

package/dist/createFlowStack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createFlowStack.js","sourceRoot":"","sources":["../src/createFlowStack.ts"],"names":[],"mappings":"AAEA,qGAAqG;AACrG,iGAAiG;AACjG,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACxB,CAAC"}

package/dist/getActiveFlowState.d.ts

@@ -0,0 +1,3 @@
+import type { FlowState, FlowStack } from '@flighthq/types';
+export declare function getActiveFlowState(stack: Readonly<FlowStack>): FlowState | null;
+//# sourceMappingURL=getActiveFlowState.d.ts.map

package/dist/getActiveFlowState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getActiveFlowState.d.ts","sourceRoot":"","sources":["../src/getActiveFlowState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,SAAS,GAAG,IAAI,CAG/E"}

package/dist/getActiveFlowState.js

@@ -0,0 +1,7 @@
+// The active top of the stack — the state currently receiving `onUpdate` — or `null` if the stack is
+// empty.
+export function getActiveFlowState(stack) {
+    const states = stack.states;
+    return states.length > 0 ? states[states.length - 1] : null;
+}
+//# sourceMappingURL=getActiveFlowState.js.map

package/dist/getActiveFlowState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getActiveFlowState.js","sourceRoot":"","sources":["../src/getActiveFlowState.ts"],"names":[],"mappings":"AAEA,qGAAqG;AACrG,SAAS;AACT,MAAM,UAAU,kBAAkB,CAAC,KAA0B;IAC3D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9D,CAAC"}

package/dist/getFlowStackDepth.d.ts

@@ -0,0 +1,3 @@
+import type { FlowStack } from '@flighthq/types';
+export declare function getFlowStackDepth(stack: Readonly<FlowStack>): number;
+//# sourceMappingURL=getFlowStackDepth.d.ts.map

package/dist/getFlowStackDepth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFlowStackDepth.d.ts","sourceRoot":"","sources":["../src/getFlowStackDepth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,MAAM,CAEpE"}

package/dist/getFlowStackDepth.js

@@ -0,0 +1,5 @@
+// The number of states on the stack.
+export function getFlowStackDepth(stack) {
+    return stack.states.length;
+}
+//# sourceMappingURL=getFlowStackDepth.js.map

package/dist/getFlowStackDepth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFlowStackDepth.js","sourceRoot":"","sources":["../src/getFlowStackDepth.ts"],"names":[],"mappings":"AAEA,qCAAqC;AACrC,MAAM,UAAU,iBAAiB,CAAC,KAA0B;IAC1D,OAAO,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;AAC7B,CAAC"}

package/dist/getFlowStackVisibleStates.d.ts

@@ -0,0 +1,3 @@
+import type { FlowState, FlowStack } from '@flighthq/types';
+export declare function getFlowStackVisibleStates(stack: Readonly<FlowStack>, out: FlowState[]): void;
+//# sourceMappingURL=getFlowStackVisibleStates.d.ts.map

package/dist/getFlowStackVisibleStates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFlowStackVisibleStates.d.ts","sourceRoot":"","sources":["../src/getFlowStackVisibleStates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAQ5D,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,IAAI,CAc5F"}

package/dist/getFlowStackVisibleStates.js

@@ -0,0 +1,22 @@
+// Fill `out` (cleared first) with the render-visible states in draw order, bottom-to-top: the active
+// top plus the contiguous run of states beneath it reachable through `renderBelow`. Walking down from
+// the top, each state that sets `renderBelow` keeps the one beneath it visible; the walk stops at the
+// first opaque state (no `renderBelow`), which is itself visible but hides everything below it. The
+// caller draws `out` front-to-back (index 0 first) so higher states paint over lower ones. `out` is
+// empty for an empty stack.
+export function getFlowStackVisibleStates(stack, out) {
+    out.length = 0;
+    const states = stack.states;
+    const top = states.length - 1;
+    if (top < 0) {
+        return;
+    }
+    let lowest = top;
+    while (lowest > 0 && states[lowest].renderBelow) {
+        lowest--;
+    }
+    for (let i = lowest; i <= top; i++) {
+        out.push(states[i]);
+    }
+}
+//# sourceMappingURL=getFlowStackVisibleStates.js.map

package/dist/getFlowStackVisibleStates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getFlowStackVisibleStates.js","sourceRoot":"","sources":["../src/getFlowStackVisibleStates.ts"],"names":[],"mappings":"AAEA,qGAAqG;AACrG,sGAAsG;AACtG,sGAAsG;AACtG,oGAAoG;AACpG,oGAAoG;AACpG,4BAA4B;AAC5B,MAAM,UAAU,yBAAyB,CAAC,KAA0B,EAAE,GAAgB;IACpF,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9B,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACZ,OAAO;IACT,CAAC;IACD,IAAI,MAAM,GAAG,GAAG,CAAC;IACjB,OAAO,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;QAChD,MAAM,EAAE,CAAC;IACX,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,IAAI,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './clearFlowStack';
+export * from './createFlowStack';
+export * from './getActiveFlowState';
+export * from './getFlowStackDepth';
+export * from './getFlowStackVisibleStates';
+export * from './popFlowState';
+export * from './pushFlowState';
+export * from './replaceFlowState';
+export * from './updateFlowStack';
+//# 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,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from './clearFlowStack';
+export * from './createFlowStack';
+export * from './getActiveFlowState';
+export * from './getFlowStackDepth';
+export * from './getFlowStackVisibleStates';
+export * from './popFlowState';
+export * from './pushFlowState';
+export * from './replaceFlowState';
+export * from './updateFlowStack';
+//# 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,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/dist/popFlowState.d.ts

@@ -0,0 +1,3 @@
+import type { FlowState, FlowStack } from '@flighthq/types';
+export declare function popFlowState(stack: FlowStack): FlowState | null;
+//# sourceMappingURL=popFlowState.d.ts.map

package/dist/popFlowState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"popFlowState.d.ts","sourceRoot":"","sources":["../src/popFlowState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAK5D,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CAU/D"}

package/dist/popFlowState.js

@@ -0,0 +1,15 @@
+// Pop the active top off the stack, exiting it (`onExit`) and resuming the state it uncovers
+// (`onResume`) — the mirror of `pushFlowState`. Returns the popped state, or `null` if the stack was
+// empty (a sentinel, not a throw — popping an empty stack is an expected no-op query).
+export function popFlowState(stack) {
+    const states = stack.states;
+    if (states.length === 0) {
+        return null;
+    }
+    const popped = states.pop();
+    popped.onExit?.();
+    const revealed = states.length > 0 ? states[states.length - 1] : null;
+    revealed?.onResume?.();
+    return popped;
+}
+//# sourceMappingURL=popFlowState.js.map

package/dist/popFlowState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"popFlowState.js","sourceRoot":"","sources":["../src/popFlowState.ts"],"names":[],"mappings":"AAEA,6FAA6F;AAC7F,qGAAqG;AACrG,uFAAuF;AACvF,MAAM,UAAU,YAAY,CAAC,KAAgB;IAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,EAAe,CAAC;IACzC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;IAClB,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtE,QAAQ,EAAE,QAAQ,EAAE,EAAE,CAAC;IACvB,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/pushFlowState.d.ts

@@ -0,0 +1,3 @@
+import type { FlowState, FlowStack } from '@flighthq/types';
+export declare function pushFlowState(stack: FlowStack, state: Readonly<FlowState>): void;
+//# sourceMappingURL=pushFlowState.d.ts.map

package/dist/pushFlowState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pushFlowState.d.ts","sourceRoot":"","sources":["../src/pushFlowState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAK5D,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAMhF"}

package/dist/pushFlowState.js

@@ -0,0 +1,11 @@
+// Push `state` onto the stack, making it the active top. The previous top (if any) is paused first
+// (`onPause`), then `state` is pushed and entered (`onEnter`) — pause-then-enter, so the outgoing
+// state is suspended before the incoming one starts.
+export function pushFlowState(stack, state) {
+    const states = stack.states;
+    const previousTop = states.length > 0 ? states[states.length - 1] : null;
+    previousTop?.onPause?.();
+    states.push(state);
+    state.onEnter?.();
+}
+//# sourceMappingURL=pushFlowState.js.map

package/dist/pushFlowState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pushFlowState.js","sourceRoot":"","sources":["../src/pushFlowState.ts"],"names":[],"mappings":"AAEA,mGAAmG;AACnG,kGAAkG;AAClG,qDAAqD;AACrD,MAAM,UAAU,aAAa,CAAC,KAAgB,EAAE,KAA0B;IACxE,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACzE,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;IACzB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;AACpB,CAAC"}

package/dist/replaceFlowState.d.ts

@@ -0,0 +1,3 @@
+import type { FlowState, FlowStack } from '@flighthq/types';
+export declare function replaceFlowState(stack: FlowStack, state: Readonly<FlowState>): void;
+//# sourceMappingURL=replaceFlowState.d.ts.map

package/dist/replaceFlowState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replaceFlowState.d.ts","sourceRoot":"","sources":["../src/replaceFlowState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAM5D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,GAAG,IAAI,CAQnF"}

package/dist/replaceFlowState.js

@@ -0,0 +1,14 @@
+// Swap the active top for `state` in place, keeping the stack depth the same. The current top (if
+// any) exits (`onExit`) and `state` enters (`onEnter`); the state beneath is NOT paused or resumed,
+// because it stays covered throughout — replace swaps the top layer, it does not uncover the one
+// below. On an empty stack this is just a push-and-enter.
+export function replaceFlowState(stack, state) {
+    const states = stack.states;
+    if (states.length > 0) {
+        const previousTop = states.pop();
+        previousTop.onExit?.();
+    }
+    states.push(state);
+    state.onEnter?.();
+}
+//# sourceMappingURL=replaceFlowState.js.map

package/dist/replaceFlowState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replaceFlowState.js","sourceRoot":"","sources":["../src/replaceFlowState.ts"],"names":[],"mappings":"AAEA,kGAAkG;AAClG,oGAAoG;AACpG,iGAAiG;AACjG,0DAA0D;AAC1D,MAAM,UAAU,gBAAgB,CAAC,KAAgB,EAAE,KAA0B;IAC3E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,WAAW,GAAG,MAAM,CAAC,GAAG,EAAe,CAAC;QAC9C,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC;IACzB,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;AACpB,CAAC"}

package/dist/updateFlowStack.d.ts

@@ -0,0 +1,3 @@
+import type { FlowStack } from '@flighthq/types';
+export declare function updateFlowStack(stack: Readonly<FlowStack>, deltaTime: number): void;
+//# sourceMappingURL=updateFlowStack.d.ts.map

package/dist/updateFlowStack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateFlowStack.d.ts","sourceRoot":"","sources":["../src/updateFlowStack.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAOjD,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAWnF"}

package/dist/updateFlowStack.js

@@ -0,0 +1,18 @@
+// Tick the stack for one frame. The active top always updates (`onUpdate(deltaTime)`); then, walking
+// downward, each visited state that sets `updateBelow` also ticks the state immediately beneath it,
+// continuing the chain until a visited state does not set `updateBelow`. So a run of transparent
+// overlays all tick their underlying states, but an opaque overlay (no `updateBelow`) freezes
+// everything below it. A no-op on an empty stack.
+export function updateFlowStack(stack, deltaTime) {
+    const states = stack.states;
+    let index = states.length - 1;
+    if (index < 0) {
+        return;
+    }
+    states[index].onUpdate?.(deltaTime);
+    while (index > 0 && states[index].updateBelow) {
+        index--;
+        states[index].onUpdate?.(deltaTime);
+    }
+}
+//# sourceMappingURL=updateFlowStack.js.map

package/dist/updateFlowStack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"updateFlowStack.js","sourceRoot":"","sources":["../src/updateFlowStack.ts"],"names":[],"mappings":"AAEA,qGAAqG;AACrG,oGAAoG;AACpG,iGAAiG;AACjG,8FAA8F;AAC9F,kDAAkD;AAClD,MAAM,UAAU,eAAe,CAAC,KAA0B,EAAE,SAAiB;IAC3E,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,IAAI,KAAK,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9B,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,OAAO;IACT,CAAC;IACD,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,CAAC;IACpC,OAAO,KAAK,GAAG,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;QAC9C,KAAK,EAAE,CAAC;QACR,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,SAAS,CAAC,CAAC;IACtC,CAAC;AACH,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/flow",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.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/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Application mode/screen flow-state stack — a plain-data stack of application states (boot, menu, play, pause, game-over) with a paired enter/exit/pause/resume/update lifecycle driven by push/pop/replace/clear transitions, transparent-overlay update-below/render-below flags, an update pass that ticks the active state and any opted-in states beneath it, and active-state/depth/visible-states queries; direct lifecycle callbacks (single-owner, deterministic order), not signals",
+  "sideEffects": false
+}

package/src/clearFlowStack.test.ts

@@ -0,0 +1,38 @@
+import type { FlowState } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { clearFlowStack } from './clearFlowStack';
+import { createFlowStack } from './createFlowStack';
+import { pushFlowState } from './pushFlowState';
+
+describe('clearFlowStack', () => {
+  it('exits every state top-to-bottom and empties the stack', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    pushFlowState(stack, labeledState('A', log));
+    pushFlowState(stack, labeledState('B', log));
+    pushFlowState(stack, labeledState('C', log));
+    log.length = 0;
+    clearFlowStack(stack);
+    expect(log).toEqual(['C.exit', 'B.exit', 'A.exit']);
+    expect(stack.states.length).toBe(0);
+  });
+
+  it('is a no-op on an empty stack', () => {
+    const stack = createFlowStack();
+    expect(() => clearFlowStack(stack)).not.toThrow();
+    expect(stack.states.length).toBe(0);
+  });
+});
+
+function labeledState(name: string, log: string[], extra: Partial<FlowState> = {}): FlowState {
+  return {
+    name,
+    onEnter: () => log.push(`${name}.enter`),
+    onExit: () => log.push(`${name}.exit`),
+    onPause: () => log.push(`${name}.pause`),
+    onResume: () => log.push(`${name}.resume`),
+    onUpdate: (deltaTime) => log.push(`${name}.update:${deltaTime}`),
+    ...extra,
+  };
+}

package/src/createFlowStack.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest';
+
+import { createFlowStack } from './createFlowStack';
+
+describe('createFlowStack', () => {
+  it('allocates an empty stack', () => {
+    const stack = createFlowStack();
+    expect(stack.states).toEqual([]);
+  });
+
+  it('allocates a fresh independent stack each call', () => {
+    const a = createFlowStack();
+    const b = createFlowStack();
+    expect(a).not.toBe(b);
+    expect(a.states).not.toBe(b.states);
+  });
+});

package/src/getActiveFlowState.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+
+import { createFlowStack } from './createFlowStack';
+import { getActiveFlowState } from './getActiveFlowState';
+import { pushFlowState } from './pushFlowState';
+
+describe('getActiveFlowState', () => {
+  it('returns the top of the stack', () => {
+    const stack = createFlowStack();
+    const a = { name: 'A' };
+    const b = { name: 'B' };
+    pushFlowState(stack, a);
+    pushFlowState(stack, b);
+    expect(getActiveFlowState(stack)).toBe(b);
+  });
+
+  it('returns null on an empty stack', () => {
+    const stack = createFlowStack();
+    expect(getActiveFlowState(stack)).toBeNull();
+  });
+});

package/src/getFlowStackDepth.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest';
+
+import { createFlowStack } from './createFlowStack';
+import { getFlowStackDepth } from './getFlowStackDepth';
+import { popFlowState } from './popFlowState';
+import { pushFlowState } from './pushFlowState';
+
+describe('getFlowStackDepth', () => {
+  it('counts the states on the stack', () => {
+    const stack = createFlowStack();
+    expect(getFlowStackDepth(stack)).toBe(0);
+    pushFlowState(stack, { name: 'A' });
+    pushFlowState(stack, { name: 'B' });
+    expect(getFlowStackDepth(stack)).toBe(2);
+    popFlowState(stack);
+    expect(getFlowStackDepth(stack)).toBe(1);
+  });
+});

package/src/getFlowStackVisibleStates.test.ts

@@ -0,0 +1,61 @@
+import type { FlowState } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createFlowStack } from './createFlowStack';
+import { getFlowStackVisibleStates } from './getFlowStackVisibleStates';
+import { pushFlowState } from './pushFlowState';
+
+describe('getFlowStackVisibleStates', () => {
+  it('fills only the top when it is opaque', () => {
+    const stack = createFlowStack();
+    const a = { name: 'A' };
+    const b = { name: 'B' };
+    pushFlowState(stack, a);
+    pushFlowState(stack, b);
+    const out: FlowState[] = [];
+    getFlowStackVisibleStates(stack, out);
+    expect(out).toEqual([b]);
+  });
+
+  it('includes the contiguous renderBelow run bottom-to-top', () => {
+    const stack = createFlowStack();
+    const a = { name: 'A' };
+    const b: FlowState = { name: 'B', renderBelow: true };
+    const c: FlowState = { name: 'C', renderBelow: true };
+    pushFlowState(stack, a);
+    pushFlowState(stack, b);
+    pushFlowState(stack, c);
+    const out: FlowState[] = [];
+    getFlowStackVisibleStates(stack, out);
+    expect(out).toEqual([a, b, c]);
+  });
+
+  it('stops at the first opaque state below a translucent overlay', () => {
+    const stack = createFlowStack();
+    const a = { name: 'A' };
+    const b = { name: 'B' };
+    const c: FlowState = { name: 'C', renderBelow: true };
+    pushFlowState(stack, a);
+    pushFlowState(stack, b);
+    pushFlowState(stack, c);
+    const out: FlowState[] = [];
+    getFlowStackVisibleStates(stack, out);
+    expect(out).toEqual([b, c]);
+  });
+
+  it('clears the out array before filling and can be reused', () => {
+    const stack = createFlowStack();
+    const a = { name: 'A' };
+    pushFlowState(stack, a);
+    const out: FlowState[] = [{ name: 'stale' }, { name: 'leftover' }];
+    getFlowStackVisibleStates(stack, out);
+    expect(out).toEqual([a]);
+  });
+
+  it('leaves the out array empty for an empty stack', () => {
+    const stack = createFlowStack();
+    const out: FlowState[] = [{ name: 'stale' }];
+    getFlowStackVisibleStates(stack, out);
+    expect(out).toEqual([]);
+  });
+});

package/src/popFlowState.test.ts

@@ -0,0 +1,54 @@
+import type { FlowState } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createFlowStack } from './createFlowStack';
+import { popFlowState } from './popFlowState';
+import { pushFlowState } from './pushFlowState';
+
+describe('popFlowState', () => {
+  it('exits the top and resumes the revealed state, returning the popped state', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    const a = labeledState('A', log);
+    const b = labeledState('B', log);
+    pushFlowState(stack, a);
+    pushFlowState(stack, b);
+    log.length = 0;
+    const popped = popFlowState(stack);
+    expect(log).toEqual(['B.exit', 'A.resume']);
+    expect(popped).toBe(b);
+    expect(stack.states.length).toBe(1);
+  });
+
+  it('returns null when the stack is empty', () => {
+    const stack = createFlowStack();
+    expect(popFlowState(stack)).toBeNull();
+  });
+
+  it('exits the last state without resuming anything below', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    pushFlowState(stack, labeledState('A', log));
+    log.length = 0;
+    popFlowState(stack);
+    expect(log).toEqual(['A.exit']);
+  });
+
+  it('does not throw when the popped state omits callbacks', () => {
+    const stack = createFlowStack();
+    stack.states.push({});
+    expect(() => popFlowState(stack)).not.toThrow();
+  });
+});
+
+function labeledState(name: string, log: string[], extra: Partial<FlowState> = {}): FlowState {
+  return {
+    name,
+    onEnter: () => log.push(`${name}.enter`),
+    onExit: () => log.push(`${name}.exit`),
+    onPause: () => log.push(`${name}.pause`),
+    onResume: () => log.push(`${name}.resume`),
+    onUpdate: (deltaTime) => log.push(`${name}.update:${deltaTime}`),
+    ...extra,
+  };
+}

package/src/pushFlowState.test.ts

@@ -0,0 +1,43 @@
+import type { FlowState } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createFlowStack } from './createFlowStack';
+import { pushFlowState } from './pushFlowState';
+
+describe('pushFlowState', () => {
+  it('enters a state pushed onto an empty stack', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    pushFlowState(stack, labeledState('A', log));
+    expect(log).toEqual(['A.enter']);
+  });
+
+  it('pauses the previous top before entering the new state', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    pushFlowState(stack, labeledState('A', log));
+    log.length = 0;
+    pushFlowState(stack, labeledState('B', log));
+    expect(log).toEqual(['A.pause', 'B.enter']);
+    expect(stack.states.length).toBe(2);
+  });
+
+  it('does not throw when the states omit lifecycle callbacks', () => {
+    const stack = createFlowStack();
+    pushFlowState(stack, {});
+    expect(() => pushFlowState(stack, {})).not.toThrow();
+    expect(stack.states.length).toBe(2);
+  });
+});
+
+function labeledState(name: string, log: string[], extra: Partial<FlowState> = {}): FlowState {
+  return {
+    name,
+    onEnter: () => log.push(`${name}.enter`),
+    onExit: () => log.push(`${name}.exit`),
+    onPause: () => log.push(`${name}.pause`),
+    onResume: () => log.push(`${name}.resume`),
+    onUpdate: (deltaTime) => log.push(`${name}.update:${deltaTime}`),
+    ...extra,
+  };
+}

package/src/replaceFlowState.test.ts

@@ -0,0 +1,47 @@
+import type { FlowState } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createFlowStack } from './createFlowStack';
+import { pushFlowState } from './pushFlowState';
+import { replaceFlowState } from './replaceFlowState';
+
+describe('replaceFlowState', () => {
+  it('exits the top and enters the replacement without touching the state below', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    const a = labeledState('A', log);
+    pushFlowState(stack, a);
+    pushFlowState(stack, labeledState('B', log));
+    log.length = 0;
+    replaceFlowState(stack, labeledState('C', log));
+    expect(log).toEqual(['B.exit', 'C.enter']);
+    expect(stack.states.length).toBe(2);
+    expect(stack.states[0]).toBe(a);
+  });
+
+  it('just pushes and enters on an empty stack', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    replaceFlowState(stack, labeledState('C', log));
+    expect(log).toEqual(['C.enter']);
+    expect(stack.states.length).toBe(1);
+  });
+
+  it('does not throw when states omit callbacks', () => {
+    const stack = createFlowStack();
+    stack.states.push({});
+    expect(() => replaceFlowState(stack, {})).not.toThrow();
+  });
+});
+
+function labeledState(name: string, log: string[], extra: Partial<FlowState> = {}): FlowState {
+  return {
+    name,
+    onEnter: () => log.push(`${name}.enter`),
+    onExit: () => log.push(`${name}.exit`),
+    onPause: () => log.push(`${name}.pause`),
+    onResume: () => log.push(`${name}.resume`),
+    onUpdate: (deltaTime) => log.push(`${name}.update:${deltaTime}`),
+    ...extra,
+  };
+}

package/src/updateFlowStack.test.ts

@@ -0,0 +1,73 @@
+import type { FlowState } from '@flighthq/types';
+import { describe, expect, it } from 'vitest';
+
+import { createFlowStack } from './createFlowStack';
+import { pushFlowState } from './pushFlowState';
+import { updateFlowStack } from './updateFlowStack';
+
+describe('updateFlowStack', () => {
+  it('ticks only the top with the frame deltaTime', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    pushFlowState(stack, labeledState('A', log));
+    pushFlowState(stack, labeledState('B', log));
+    log.length = 0;
+    updateFlowStack(stack, 0.016);
+    expect(log).toEqual(['B.update:0.016']);
+  });
+
+  it('ticks the state beneath a transparent updateBelow overlay', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    pushFlowState(stack, labeledState('A', log));
+    pushFlowState(stack, labeledState('B', log, { updateBelow: true }));
+    log.length = 0;
+    updateFlowStack(stack, 0.02);
+    expect(log).toEqual(['B.update:0.02', 'A.update:0.02']);
+  });
+
+  it('does not tick below an opaque overlay', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    pushFlowState(stack, labeledState('A', log));
+    pushFlowState(stack, labeledState('B', log));
+    log.length = 0;
+    updateFlowStack(stack, 0.01);
+    expect(log).toEqual(['B.update:0.01']);
+  });
+
+  it('walks a chain of updateBelow overlays and stops at the first opaque one', () => {
+    const log: string[] = [];
+    const stack = createFlowStack();
+    pushFlowState(stack, labeledState('A', log));
+    pushFlowState(stack, labeledState('B', log));
+    pushFlowState(stack, labeledState('C', log, { updateBelow: true }));
+    pushFlowState(stack, labeledState('D', log, { updateBelow: true }));
+    log.length = 0;
+    updateFlowStack(stack, 0.5);
+    expect(log).toEqual(['D.update:0.5', 'C.update:0.5', 'B.update:0.5']);
+  });
+
+  it('is a no-op on an empty stack', () => {
+    const stack = createFlowStack();
+    expect(() => updateFlowStack(stack, 0.016)).not.toThrow();
+  });
+
+  it('does not throw when a ticked state omits onUpdate', () => {
+    const stack = createFlowStack();
+    stack.states.push({ updateBelow: true }, {});
+    expect(() => updateFlowStack(stack, 0.016)).not.toThrow();
+  });
+});
+
+function labeledState(name: string, log: string[], extra: Partial<FlowState> = {}): FlowState {
+  return {
+    name,
+    onEnter: () => log.push(`${name}.enter`),
+    onExit: () => log.push(`${name}.exit`),
+    onPause: () => log.push(`${name}.pause`),
+    onResume: () => log.push(`${name}.resume`),
+    onUpdate: (deltaTime) => log.push(`${name}.update:${deltaTime}`),
+    ...extra,
+  };
+}