Directives

What you will find: a precise, alphabetical-by-category reference of every directive and shorthand Sercrod recognizes. Each entry states the value form, when it is evaluated, and what side effects it has on data, attributes, DOM, and events. No tutorials or design commentary are included.

Conventions

• All directives have two equivalent forms: the asterisk form (*if) and the n- form (n-if). This page lists the asterisk form for brevity.
• Expressions are JavaScript evaluated in the current scope. In event handlers, $event is the native DOM event and el is the element that holds the handler.
• Text interpolation uses %expr%. Output directives control whether text or HTML is emitted.
• Transient stores such as $response are cleared automatically in the finalization step of the update cycle that produced them. Communication directives write ordinary data only when *response or its *into compatibility alias asks for it. *download reports through events instead of writing response data.

1) Control flow

*if="expr"

• When: render time and on updates.
• Effect: renders the element and its subtree only if expr is truthy. Otherwise the element is removed from the rendered output.

*elseif="expr"

• When: render time and on updates.
• Effect: used immediately after an *if or another *elseif. Renders the element only if all previous conditions in the same chain were falsy and expr is truthy.

*else

• When: render time and on updates.
• Effect: final branch in an *if chain. Renders only if all previous *if/*elseif conditions in the same chain were falsy.

*switch="expr"

• When: render time and on updates.
• Effect: activates the first matching *case in the same switch group, otherwise *default if present. Matching is strict equality (===) against each case value.

*case="valueExpr"

• When: evaluated within the nearest active *switch.
• Effect: renders this element if valueExpr === <switch-expr>. May be combined with .break (see below).

*case.break="valueExpr"

• When: same as *case.
• Effect: same as *case, and prevents any subsequent cases in the same switch group from rendering.

*break

• When: inside a *switch group.
• Effect: stops further case evaluation and rendering within the same switch group.

2) Iteration

*each="iterableExpr as item[, index]"

• When: render time and on updates when iterableExpr changes.
• Effect: repeats the element once per entry in an array or object.
  • For arrays: item is the value, index is the numeric index.
  • For objects: item is the value, index is the property key.

*for="loopExpr"

• When: render time and on updates.
• Effect: low-level looping. loopExpr must evaluate to an iterable or a structure that Sercrod can iterate. Each iteration renders one instance of the element. Use *each for common array/object cases.

*iterate="iterableExpr"

• When: render time, and during placement sync when a host with *dominate receives an automatic update. The older *dominant spelling remains accepted as an alias.
• Effect: on a native <template> anchor, synchronizes child placement from an iterable without rebuilding the parent host. The short form *iterate="rows" uses item as the current value name and item.type as the registered *template selector.
• Notes: array order is authoritative. id, key, and *keys are not used. The same item object keeps its DOM record when moved; a changed template selector replaces that item with another template. A child <serc-rod data="item"> produced by placement receives item as its data root. Use object form { iterable, variable, template } when the data shape does not follow the default item.type convention.

3) Variables and scope

*let="assignments"

• Form: one or more comma-separated assignments, e.g. *let="x = 1, y = x + 2".
• When: evaluated before rendering the element.
• Effect: defines or updates variables in the current scope for this subtree. During *let evaluation, $parent is injected and points to the nearest ancestor host’s data (read-write).

*global="assignments"

• When: before rendering the element.
• Effect: writes named values either to the host data if a same-named key exists, otherwise to globalThis. Use to expose values across hosts intentionally.

*literal="jsonLike"

• When: before rendering the element.
• Effect: injects a literal object/array/value into scope without expression evaluation side effects.

*rem="comment"

• When: parse time.
• Effect: documentation-only marker. Has no runtime effect.

4) Input and staging

*input="pathExpr"

• When: render time; listens to input-like events (input, change, composition events, and click on form controls).
• Effect: two-way binding between a form control and pathExpr.
  • Incoming values pass through input_in filter.
  • Outgoing values pass through input_out filter.
  • If staging is enabled (see *stage), writes go to the stage buffer instead of the main data.

*lazy

• When: with *input.
• Effect: defers updates to change or blur-like points depending on the control type.

*eager

• When: with *input.
• Effect: updates on input continuously.

*stage

• When: before rendering the element.
• Effect: enables a per-host staging buffer. Subsequent *input writes go to the staged copy.

*apply

• When: on evaluation.
• Effect: copies staged values into the main data. No effect if staging is not active.

*restore

• When: on evaluation.
• Effect: discards staged changes. No effect if staging is not active.

*save

• When: on evaluation.
• Effect: serializes the current data to a downloadable JSON file. Filename is implementation-defined.

*load

• When: user selects a JSON file.
• Effect: reads JSON and merges values into the host data. Triggers a normal update cycle.

5) Output

*print="expr"

• When: on render and updates.
• Effect: sets the element’s text content to the evaluated result of expr after applying text-related filters.

*compose="expr"

• When: on render and updates.
• Effect: sets the element’s HTML content to the evaluated result of expr after applying HTML-related filters.

*textContent="expr" / *innerHTML="expr"

• Effect: synonyms for *print and *compose respectively.

Non-structural change path

• When: after Sercrod knows that a data key or path changed.
• Effect: text output bindings such as *print, *textContent, and simple interpolation may update through registered change commands instead of rebuilding the host.
• Notes: this is not DOM diffing. Sercrod does not compare old DOM and new DOM, and it does not search the DOM for changes. A known data path change is routed to already registered DOM commands.

6) Attributes and shorthands

:class="expr" (alias: n-class="expr")

• When: on render and updates.
• Effect: updates the class attribute. expr may be a string, an array of class names, or an object map {name: boolean}. The attr filter applies.

:style="expr" (alias: n-style="expr")

• When: on render and updates.
• Effect: updates inline style. expr may be a CSS string or an object map {prop: value}. The style filter applies.

Attribute change commands

• When: after Sercrod knows that a data key or path used by an attribute binding changed.
• Effect: attribute bindings, including :class, :style, and form value/checked-like property reflection where supported, may update through registered non-structural change commands.
• Notes: structural directives such as *for, *each, *iterate, *if, template cloning, insertion, removal, and reorder keep their existing rendering behavior.

7) Communication (HTTP and API)

*fetch[="urlExpr"]

• When: on render and when its parameters change or the host is force-updated.
• Effect: performs a GET request. If the response is JSON, stores the parsed object into the host data.
  • Storage target: use *response for ordinary response placement.
  • Compatibility: the older URL:prop suffix is still accepted when *response is absent, but should not be used in new examples.

*post="urlExpr"

• When: on evaluation.
• Effect: performs a POST with a Sercrod request envelope. *keys selects outgoing data; *params adds request metadata; *dry-run marks intent; *response maps the parsed response.

*api="expr"

• When: on evaluation.
• Effect: performs an HTTP request defined by expr, method, and optional body / payload. Emits completion events. Supports *params, *dry-run, file inputs, and *response.

*response="target"

• When: with HTTP, load, upload, adapter action, or WebSocket directives that produce a result.
• Effect: places or maps the result into host data. Quoted strings store the whole result under that data key. Object form maps result fields into data paths.

*into="name"

• When: only as compatible syntax on directives that support simple whole-result placement.
• Effect: stores the whole result under one top-level key. Use *response in new templates.

8) Files

*camera, *camera.capture, *camera.pick

• When: explicit click or Enter/Space keyboard activation.
• Effect: delegates to the sercrod.camera adapter to capture a new image or pick an existing image.
  • Events: sercrod-camera-start, sercrod-camera, sercrod-camera-cancel, sercrod-error.
  • Result storage: writes successful normalized image results to $camera, and applies *response / *into placement when present.
  • Boundary: does not save, upload, or persist images.

*clipboard, *clipboard.write, *clipboard.copy, *clipboard.read

• When: explicit click or Enter/Space keyboard activation.
• Effect: delegates to the sercrod.clipboard adapter to write or read clipboard text.
  • Formats: .text, .raw, .json, and .lines.
  • Events: sercrod-clipboard-start, sercrod-clipboard-written, sercrod-clipboard-read, sercrod-error.
  • Result storage: writes $clipboard and $clipboard_text, and applies *response / *into placement when present.
  • Boundary: not for ordinary internal data transfer; use Sercrod data or storage for that.

*audio-capture, *audio-capture.start, *audio-capture.pause, *audio-capture.resume, *audio-capture.stop, *audio-capture.cancel

• When: explicit click or Enter/Space keyboard activation.
• Effect: delegates to the sercrod.audio_capture adapter to control microphone recording.
  • Events: sercrod-audio-capture-start, sercrod-audio-capture, sercrod-audio-capture-cancel, sercrod-error.
  • Result storage: writes $audio_capture and $audio_capture_status; stop applies *response / *into placement when present.
  • Boundary: native <audio> remains preview/playback UI; save, upload, transcription, mixing, and background recording are separate.

*geolocation, *geolocation.current, *geolocation.watch, *geolocation.clear

• When: current, clear, and permission forms run on explicit click or Enter/Space keyboard activation. watch runs on explicit activation for clickable elements and auto-starts once on non-clickable elements.
• Effect: delegates to the sercrod.geolocation adapter for foreground position actions.
  • Permission forms: *geolocation.check-permissions and *geolocation.request-permissions.
  • Events: sercrod-geolocation-start, sercrod-geolocation, sercrod-geolocation-watch, sercrod-geolocation-clear, sercrod-geolocation-permissions, sercrod-error.
  • Result storage: writes $geolocation, $geolocation_position, $geolocation_watch_id, and $geolocation_permissions; applies *response / *into placement when present.
  • Boundary: maps, geocoding, IP estimation, route history, persistence, upload, and background tracking are outside the directive.

*network-status, *network-status.current, *network-status.watch, *network-status.clear

• When: current and clear run on explicit click or Enter/Space keyboard activation. watch runs on explicit activation for clickable elements and auto-starts once on non-clickable elements.
• Effect: delegates to the sercrod.network_status adapter for online/offline status and connection information.
  • Events: sercrod-network-status-start, sercrod-network-status, sercrod-network-status-watch, sercrod-network-status-clear, sercrod-error.
  • Result storage: writes $network_status, $network_status_watch_id, and applies *response / *into placement when present.
  • Boundary: network status does not retry requests, schedule uploads, manage WebSocket reconnection, synchronize app state, install service workers, or make app policy decisions.

*diagnostics, *diagnostics.send, *diagnostics.clear

• When: host *diagnostics starts on connection. send and clear run on explicit click or Enter/Space keyboard activation.
• Effect: delegates structured Sercrod and supported browser diagnostics to sercrod.diagnostics.
  • Events: sercrod-diagnostics-start, sercrod-diagnostics-queued, sercrod-diagnostics-sent, sercrod-diagnostics-dropped, sercrod-diagnostics-report, sercrod-diagnostics-cleared.
  • Result storage: writes local action status to $diagnostics; transmitted records do not use *response.
  • Boundary: diagnostics cannot read all DevTools output or native logs and does not replace Playwright.

*screen-state, *screen-state.current, *screen-state.watch, *screen-state.clear

• When: current and clear run on explicit click or Enter/Space keyboard activation. watch runs on explicit activation for clickable elements and auto-starts once on non-clickable elements.
• Effect: delegates to the sercrod.screen_state adapter for viewport, orientation, fullscreen, and display-mode state.
  • Events: sercrod-screen-state-start, sercrod-screen-state, sercrod-screen-state-watch, sercrod-screen-state-clear, sercrod-error.
  • Result storage: writes $screen_state, $screen_state_watch_id, and applies *response / *into placement when present.
  • Boundary: screen state does not edit viewport meta tags, replace CSS media/container queries, compute layouts, route pages, persist state, or make app policy decisions.

*wake-lock, *wake-lock.request, *wake-lock.release, *wake-lock.status

• When: request and status run on explicit activation for clickable elements and auto-start once on non-clickable elements. release always runs on explicit click or Enter/Space keyboard activation.
• Effect: delegates to the sercrod.wake_lock adapter to request, release, or inspect a screen wake lock.
  • Events: sercrod-wake-lock-start, sercrod-wake-lock, sercrod-error.
  • Result storage: writes $wake_lock, $wake_lock_active, and applies *response / *into placement when present.
  • Boundary: wake lock does not control media playback, timers, notifications, app lifecycle, background execution, or OS battery policy.

*haptics, *haptics.impact, *haptics.selection, *haptics.notification, *haptics.vibrate, *haptics.status

• When: feedback actions run on explicit click or Enter/Space keyboard activation. status runs on explicit activation for clickable elements and auto-starts once on non-clickable elements.
• Effect: delegates to the sercrod.haptics adapter for tactile feedback and support status.
  • Events: sercrod-haptics-start, sercrod-haptics, sercrod-error.
  • Result storage: writes $haptics, $haptics_supported, and applies *response / *into placement when present.
  • Boundary: haptics does not create gestures, handle pointer events, play sound, animate UI, show notifications, navigate, or make app policy decisions.

*share

• When: explicit click or Enter/Space keyboard activation.
• Effect: delegates to the sercrod.share adapter to share text, URLs, or supported files.
  • Payload: expression object with title, text, url, and optional files; string expressions become text.
  • Events: sercrod-share-start, sercrod-share, sercrod-share-fallback, sercrod-share-cancel, sercrod-error.
  • Result storage: writes $share, and applies *response placement when present.
  • Boundary: sharing does not save, upload, navigate, persist data, or write to the clipboard.

*notification

• When: explicit click or Enter/Space keyboard activation.
• Effect: delegates to the sercrod.notification adapter for local notification actions.
  • Action forms: *notification, *notification.show, *notification.check-permissions, and *notification.request-permissions.

*push

• Register for remote push and expose normalized permission, token, receive, and notification action results through sercrod.push.
• Action forms: *push, *push.register, *push.unregister, *push.check-permissions, *push.request-permissions, *push.watch, and *push.clear.
• Register and permission actions are explicit. Watch auto-starts once only on non-clickable declarations.
• A declared registration endpoint receives { action, registration }; this directive does not send notifications or own server infrastructure.
  • Events: sercrod-notification-start, sercrod-notification, sercrod-notification-fallback, sercrod-notification-permissions, sercrod-error.
  • Result storage: writes $notification and $notification_permissions; applies *response placement when present.
  • Boundary: notifications do not implement push registration, server delivery, background sync, persistence, sharing, or navigation.

*background-notification

• Delegates short, notification-specific server checks to Capacitor Background Runner; it does not execute Sercrod or keep a WebView alive in the background.
• Action forms: *background-notification, .configure, .enable, .disable, .check-now, .status, .check-permissions, and .request-permissions.
• The endpoint returns HTTP 204 for no update or JSON with a notification object for a local notification.
• Android's requested repeat interval is at least 15 minutes and inexact. iOS determines execution timing and normally limits one invocation to about 30 seconds.
• Background Runner registration is build-time configuration. Disable stores a flag that makes scheduled invocations exit without a request.
• Boundary: no WebSocket, remote push, UI launch, background Sercrod directive execution, exact timing, or delivery guarantee.

*foreground-notification

• Android-only self-hosted realtime notification route through sercrod.foreground_notification.
• Action forms: *foreground-notification, .start, .stop, .status, .check-permissions, and .request-permissions.
• The native foreground service keeps a WebSocket connected and displays local notifications; it does not run Sercrod or the WebView in the background.
• Android requires an ongoing notification. There is no general-purpose iPhone equivalent; timely iPhone delivery uses APNs.

*barcode

• When: explicit click or Enter/Space keyboard activation.
• Effect: delegates to the sercrod.barcode adapter to scan or detect barcodes and QR codes.
  • Action forms: *barcode, *barcode.scan, and *barcode.detect.
  • Events: sercrod-barcode-start, sercrod-barcode, sercrod-barcode-fallback, sercrod-error.
  • Result storage: writes $barcode and $barcode_results; applies *response placement when present.
  • Boundary: barcode does not capture photos as camera, upload images, validate inventory/payment flows, or navigate from scanned values.

*upload="targetExpr"

• When: user selects files via the control.
• Effect: sends selected files using XHR with progress events.
  • Events: sercrod-upload-start, sercrod-upload-progress, sercrod-uploaded.
  • Result storage: mirrors parsed responses to $response and applies *response / *into placement when present.

*download="urlOrBlobExpr"

• When: on evaluation.
• Effect: downloads a resource or generated Blob.
  • Events: sercrod-download-start, sercrod-downloaded.
  • Result storage: does not write to host data.

9) WebSocket

*websocket="urlExpr"

• When: on render and when parameters change or the host is force-updated.
• Effect: opens a WebSocket connection.
  • State keys on host data: $ws_ready, $ws_error, $ws_last, $ws_messages[], $ws_closed_at, $ws_close_code, $ws_close_reason.
  • Events: sercrod-ws-before-connect, sercrod-ws-open, sercrod-ws-message (payload JSON auto-detected), sercrod-ws-error, sercrod-ws-close.
  • Host exposes methods under el.websocket.{connect,reconnect,close,send,status,urls}.

*ws-send="payloadExpr"

• When: on evaluation.
• Effect: sends a string or JSON-serializable payload to the active socket associated with the host. If multiple sockets are managed, resolution follows the host’s current el.websocket.status() rules.

10) Events and handlers

@type="expr" (event handler)

• When: native event dispatch.
• Effect: evaluates expr in a context where $event is the DOM event and el is the current element.
• Modifiers: append with dots to the event name.
  • .prevent → event.preventDefault()
  • .stop → event.stopPropagation()
  • .once → addEventListener(..., { once: true })
  • .capture → listener in capture phase
  • .passive → passive listener
  • .update → force a host update after handler execution
  • .noupdate → suppress auto-update for this handler
• Auto-update policy: input-like events schedule updates by default. Use .noupdate to opt out or .update to force an update on non-input events.

11) Lifecycle helpers and methods

*updated="handlers"

• When: after initialization and after each update cycle.
• Effect: invokes named functions or all function properties of a named object. handlers can be a comma-separated list of function names or object identifiers.

*update="target"

• When: after this host or element has been updated.
• Effect: forces one target Sercrod host to update. The value is a literal target spec such as root, 2, or (#parent).
• Compatibility: *updated-propagate remains available for older templates, but new documentation and examples should use *update.

*methods="namesOrObjects"

• When: before rendering the element.
• Effect: injects named global functions and/or all function properties of named global objects into the expression scope of this host.

*log="expr"

• When: on evaluation.
• Effect: writes the evaluated value to the console for inspection. No side effects.

*strict

• When: before rendering the element.
• Effect: turns on stricter evaluation rules for this subtree as defined by the current implementation’s strict mode.

*prevent-default

• When: on evaluation.
• Effect: attaches default-prevention behavior in contexts where no @ handler is used. Prefer handler modifiers when possible.

Errors and events

• Failures in network, file, or WebSocket operations emit corresponding events (sercrod-error and operation-specific events). Implementations may also log warnings.
• Directives that assign to data keys update host data and schedule rendering because the directive is a Sercrod-owned update entry point.

Next page: lifecycle.md