Relative include paths are resolved based to the current desktop's path (which is the location of the main.zul currently displayed).
If you want to check this in code place a breakpoint in AbstractExecution:toAbsolutePath() and observe which uri is passed in and which currentDirectory is prepended.
(This process is independent of any components, so <hbox> has nothing to do with it. Also this is independent of dynamic usage.)
Assume this static structure:
/pages/main.zul
/pages/sub/sub.zul
/pages/sub/sub-include.zul
main.zul
<div>
<include src="sub/sub.zul"/>
</div>
sub/sub.zul
<div>
SUB
<div>
<include src="sub-include.zul"/>
</div>
</div>
Will result in this error:
org.zkoss.zk.ui.UiException: Page not found: /pages/sub-include.zul
at org.zkoss.zk.ui.http.ExecutionImpl.getPageDefinition(ExecutionImpl.java:385)
at org.zkoss.zul.Include.afterCompose(Include.java:509)
...
Changing the included src url like below will fix this issue.
<include src="sub/sub-include.zul"/>
I agree this is not obvious, but that's how it behaves.
A more robust alternative is to use absolute paths (starting with a /) to avoid relative path resolution issues.
<include src="/pages/sub/sub-include.zul"/>