Host.historyPushLocation
luastra/hostHost.historyPushLocation(location: string, stateToken: string): RequestId
Adds a browser-history entry containing both a canonical location and an opaque application state token, then returns the document viewport to its start. This keeps the address bar, deep-link representation, application stack, and newly opened page position synchronized.
Before you use it
Add luastra/host to this module's dependencies in luastra.json, then import it with require("luastra/host"). Declare navigation.history in luastra.json. Save the returned RequestId with its purpose and implement app.resolve.
How it fits
The function starts an asynchronous host request and returns immediately. app.resolve receives its success payload or stable failure code; availability and permission can vary by host.
When to use it
Use Host.historyPushLocation after a successful typed route mutation that should be reversible with Back. Generate the location through Navigation.compile rather than concatenating untrusted path or query fragments.
Parameters
| Parameter | Type / values | Description |
|---|---|---|
| location | string | Canonical admitted location for the new entry. |
| stateToken | string | Opaque encoded application state associated with that location. |
Returns
RequestId — an opaque request identifier used to correlate the asynchronous completion in app.resolve.
What happens next
A RequestId now, followed later by one matching app.resolve completion.
Failures and fixes
Undeclared capability, unavailable host support, denied permission, invalid input, deadline, network, or internal failure reaches the bounded failure path. Public completion codes are CANCELLED, DEADLINE, FORBIDDEN, INTERNAL, NETWORK, UNAUTHORIZED, and VALIDATION.
Availability
Public-source alpha capability API in 0.5.0-alpha; verify each claimed host independently.
Focused example
local Host = require("luastra/host")
Host.historyPushLocation("#/card/red", router.encode())Continue with a complete recipe
This checked recipe uses Host.historyPushLocation inside complete authored files with the required manifest, test, and run steps.
Open synchronize Browser and system Back recipe