Lifecycle Directives

Lifecycle directives control how data flows over time in a Sercrod host: staged edits, saving and loading, HTTP requests, file transfer, and real-time connections.

This page groups lifecycle-related directives by purpose. For the host update lifecycle and render order, see Runtime Behavior.

For JavaScript integration after startup, each host exposes host.ready and dispatches sercrod-ready once after its first completed update() cycle. This is host state, not a directive and not a data field.

Staging Edits

Staging directives let a user edit a temporary branch and then explicitly commit or discard those changes.

• *stage marks a subtree as working on staged data instead of the main data.
• *apply commits staged values back to the main data.
• *restore discards staged changes and restores from the previous main data.

<serc-rod
    id="profile-app"
    data='{"profile":{"name":"Taro","email":"taro@example.com"}}'
>
    <form *stage>
        <label>
            Name:
            <input type="text" :value="profile.name">
        </label>

        <label>
            Email:
            <input type="email" :value="profile.email">
        </label>

        <button type="button" *apply>Save</button>
        <button type="button" *restore>Reset</button>
    </form>

    <p>Current name: %profile.name%</p>
    <p>Current email: %profile.email%</p>
</serc-rod>

Use staging when a user should be able to edit a complex form and then explicitly commit or discard changes.

Saving And Loading

*save.file, *load.file, *save.session, *load.session, *save.store, and *load.store coordinate host data with local persistence.

• *save.file serializes host data and triggers a download.
• *load.file loads JSON from a user-selected file into host data.
• *save.session and *load.session use browser sessionStorage.
• *save.store and *load.store use IndexedDB-backed persistent browser storage.
• *keys selects which top-level keys are included.

The runtime dispatches sercrod-loaded and sercrod-saved hooks for successful operations.

<serc-rod data='{"todos":[]}'>
    <ul>
        <li *for="item of todos">%item.label%</li>
    </ul>

    <button type="button" *load.file>Load</button>
    <button type="button" *save.file>Save</button>
    <button type="button" *save.store="'todos'" *keys="todos">Save store</button>
    <button type="button" *load.store="'todos'" *keys="todos">Load store</button>
</serc-rod>

Use save/load when state should be exported, restored, or kept locally in the browser by explicit user action.

HTTP Lifecycle

HTTP directives coordinate requests and how responses enter host data.

• *fetch loads JSON-like data from a URL.
• *post sends host data or staged data as JSON.
• *api is the more general HTTP primitive for method, body, upload, status, and *response.
• *response selects result placement for HTTP, load, upload, adapter, and WebSocket flows. *into is a compatibility alias for simple whole-result placement.

For request timing and response shape contracts, see Network Contracts.

File Transfer

*upload and *download provide file transfer behavior.

• *upload binds an element as an upload trigger and sends selected files.
• *download downloads a resource or generated response.

The runtime exposes progress and completion through custom events:

• sercrod-upload-start
• sercrod-upload-progress
• sercrod-uploaded
• sercrod-download-start
• sercrod-downloaded
• sercrod-error

Upload results are mirrored to $response and may be placed through *response or its *into alias. *download does not write result data into the host; it emits download events.

Real-Time Lifecycle

WebSocket directives connect a host to a WebSocket server.

• *websocket opens and manages the connection.
• *ws-send sends a payload through the active connection.
• *ws-to selects a target WebSocket URL when multiple connections are present.

WebSocket state is reflected through data fields such as $ws_ready, $ws_last, $ws_messages, $ws_error, and close information.

See WebSocket.

Choosing Lifecycle Directives

• Use staging directives for edit-then-commit forms.
• Use save/load for user-visible export and restore flows.
• Use HTTP directives for JSON endpoints and API operations.
• Use file directives for upload and download operations.
• Use WebSocket directives for live updates and bidirectional communication.