runtime

func AddClass ¶

func AddClass(id, className string)

func AddEventListener ¶

func AddEventListener(el JSValue, event string, fn func())

AddEventListener attaches a persistent event listener to el for the given event name. fn is called with no arguments each time the event fires. The js.Func is retained in keep and never released — persistent listeners must stay alive for the lifetime of the page; releasing them would panic on the next event.

func AddEventListenerWithEvent ¶

func AddEventListenerWithEvent(el JSValue, event string, fn func(JSValue))

AddEventListenerWithEvent attaches a persistent event listener to el for the given event name. fn receives the browser Event object as a JSValue, giving access to event properties and methods such as preventDefault(), stopPropagation(), event.target, event.key, event.detail, etc. The js.Func is retained in keep and never released — persistent listeners must stay alive for the lifetime of the page; releasing them would panic on the next event.

func AppendChild ¶

func AppendChild(parent, child JSValue)

Element tree helpers.

func BeginBatch ¶

func BeginBatch()

BeginBatch defers observer notifications until the matching EndBatch. Nested calls are supported; effects only flush when depth returns to 0. Each pending Subscription is deduplicated and runs at most once per batch.

func BroadcastTopicEncoded ¶

func BroadcastTopicEncoded(keyName, encoded string)

BroadcastTopicEncoded writes encoded to the JS store and dispatches a CustomEvent.

func BroadcastTopicEncodedField ¶

func BroadcastTopicEncodedField(keyName, fieldName, encoded string)

BroadcastTopicEncodedField broadcasts an already-encoded single field value. Event name: "gothic:topic:<keyName>:<fieldName>"

func BroadcastTopicOnline ¶

func BroadcastTopicOnline(keyName, encoded string)

BroadcastTopicOnline dispatches the online ack to all consumer WASMs for this key.

func CaptureScope ¶

func CaptureScope() string

CaptureScope returns the scope active at the call site. Capture it before spawning a goroutine or scheduling async work whose body touches scoped DOM helpers, then re-establish it with RunInScope when that work runs — a goroutine does not inherit the carrier across a suspension point.

Keep any blocking call (a fetch, a channel receive) OUTSIDE RunInScope and wrap only the scoped, non-blocking work — mirroring how PingUntilOnline keeps time.Sleep outside RunInScope:

scope := CaptureScope()
go func() {
    body, _ := Fetch(url)                       // blocks — outside RunInScope
    RunInScope(scope, func() { SetText("out", body) })  // scoped, non-blocking
}()

func ClickElement ¶

func ClickElement(el JSValue)

func ConsoleLog ¶

func ConsoleLog(args ...any)

func CookieDelete ¶

func CookieDelete(key string)

CookieDelete expires a cookie immediately.

func CookieGet ¶

func CookieGet(key string) string

CookieGet reads a cookie value from document.cookie. Returns "" for missing or HttpOnly cookies.

func CookieSet ¶

func CookieSet(key, value string, opts ...CookieOptions)

CookieSet writes a cookie to document.cookie.

func CopyBytesToGo ¶

func CopyBytesToGo(dst []byte, src JSValue) int

func CopyBytesToJS ¶

func CopyBytesToJS(dst JSValue, src []byte) int

func CreateTopic ¶

func CreateTopic[T any](zero T, cfg TopicConfig) func() interface{}

CreateTopic declares a topic. The CLI AST scanner detects this call and generates the concrete typed accessor. At runtime this returns a no-op.

func CreateWasmBoolFunc ¶

func CreateWasmBoolFunc(name string, fn func(bool))

func CreateWasmFunc ¶

func CreateWasmFunc(name string, fn func())

CreateWasmFunc registers a no-arg user callback under name. The Go closure becomes a js.Func stored in __gothic_registry[scope][name] (registerLocal), keyed by the active scope. That registry js.Func is the SOLE dispatch target: the GLOBAL proxy window[name] — the function HTML onclick/onchange invokes — is pure, instance-agnostic JS installed once per name by __gothicInstallProxy (see pkg/helpers/gothiccore/core.go). On each click that proxy resolves the clicked element's scope off the LIVE __gothic_registry and calls this scope's js.Func, so tearing down a sibling instance (which deletes its registry entry) can never leave the proxy pointing at halted Go code.

func CreateWasmStringFunc ¶

func CreateWasmStringFunc(name string, fn func(string))

func DurableKey ¶

func DurableKey() string

DurableKey returns the STABLE durable key declared on the active scope's wrapper (data-gothic-durable-key), or "" when the placement is not durable. The DOM read lives in JS (window.__gothicDurableKey in gothic-core.js) and returns a plain string so no per-mount MouseEvent/element js.Value is boxed into TinyGo's slot table (the same _values[]-leak avoidance as findScope). Empty string is the default and means "durability off" — callers treat it as opt-out.

func DurableObserve ¶

func DurableObserve[T any](field string, obs *Observable[T], encode func(T) string, decode func(string) T)

DurableObserve binds obs to the core's durable KV as `field` under this placement's durable key. It rehydrates obs from the core BEFORE the component goes live, then persists every subsequent change for the page session. When the placement has NO durable key it is a NO-OP and obs behaves exactly as today (OPT-IN; default off). encode/decode are the field's string codec (same shape as CustomKey — reuse strconv for primitives, or a binary Encoder/Decoder for a struct field); they exist in both build worlds so the same ClientSideState block compiles server-side (no-op) and under TinyGo.

count := CreateObservable(0)
DurableObserve("count", count, strconv.Itoa,
    func(s string) int { n, _ := strconv.Atoi(s); return n })
Observe(func() { SetText("out", strconv.Itoa(count.Get())) }, count)

func EndBatch ¶

func EndBatch()

EndBatch decrements the batch depth and, when it reaches zero, runs every Subscription that was queued during the batch (deduplicated).

func ExecJS ¶

func ExecJS(script string)

ExecJS executes the given script string in the global scope.

func Fetch ¶

func Fetch(url string, config ...FetchConfig) (string, error)

Fetch makes an HTTP request using the browser's fetch API and blocks until complete.

func FetchBytes ¶

func FetchBytes(url string, config ...FetchConfig) ([]byte, error)

FetchBytes makes an HTTP request and returns the response as raw bytes. Use for binary responses (images, PDFs, ZIPs) where Fetch's text() decoding would corrupt data.

func GetFileBytes ¶

func GetFileBytes(id string) []byte

GetFileBytes reads the contents of the first selected file from a <input type="file"> element. Blocks until the FileReader completes. Returns nil on error or if no file is selected.

func GetValue ¶

func GetValue(id string) string

func GoBack ¶

func GoBack()

func GothicHaltChan ¶

func GothicHaltChan() <-chan struct{}

GothicHaltChan returns the keep-alive sentinel channel. The generated WASM main() selects on it so the module returns when the bootstrap's per-scope teardown invokes this instance's __gothic_halt callback.

func GothicRegisterSchema ¶

func GothicRegisterSchema(key, schemaID, descriptor string)

GothicRegisterSchema records a topic/component type's compact schema descriptor under its content-hash id at the point the type registers. This is the Phase 15 SCHEMA SEAM: a reserved, additive control-plane slot for a future generic wire interpreter (Phase 16's core stores it opaquely). NOTHING interprets it in v3.0 — it is written once, off the data-plane, and never read back by any 3.0 consumer. The descriptor is deposited on window.__gothicSchemas (keyed by schemaID) so the core can later pick it up without a wire change.

Generated code only (like the Broadcast*/Listen* helpers); it is never hand-written in a ClientSideState block, so it has no user-facing stub-parity obligation.

func GothicRegisterScope ¶

func GothicRegisterScope(body func())

GothicRegisterScope wires a Multiplexed page's ClientSideState body into the per-scope registration system. The generated main() of a Multiplexed route calls it with the ClientSideState body wrapped in a closure, instead of running that body inline. It:

1. Registers the instance's own mount scope immediately by running body under runInScope(bootstrapScope). This makes the first placement behave exactly like a non-multiplexed instance: body runs under the bootstrap scope, so its observables/callbacks/listeners land in __gothic_registry[bootstrapScope] — byte-identical to the non-multiplexed registration path.

2. Publishes a per-instance __gothic_register_scope(id) callback onto this module's window.__gothicInstances[<bootstrapScope>] slot (the same slot the Phase-12 __halt lives on). The bootstrap JS invokes it for every SUBSEQUENT placement of the same component type, running the SAME body under runInScope(id). Each invocation re-runs body, creating FRESH observables and callbacks via new closures — this is why Phase 13's scope refactor is the gate for multiplexing: one instance hosts N independent scopes, each with its own state, all resolved per active scope.

Publishing onto the per-instance slot (not a window global) mirrors __halt: portable across the GothicTinyGo/LocalTinyGo/Golang compilers AND correct on a multi-instance page. main() runs synchronously up to its keep-alive select during go.run, so the callback is set before the bootstrap flushes its pending queue.

func GothicRegisterWithCore ¶

func GothicRegisterWithCore(scopeID, schemaID, schema string)

GothicRegisterWithCore performs the component→core registration RPC against the Phase-16 full-Go static core over the `document` control-plane bus. It hands the core an OPAQUE schema descriptor keyed by (scopeID, schemaID): the core records {scopeId, schemaId, schema} verbatim and acks — it never interprets the descriptor (the generic interpreter is DEFERRED).

Ordering mirrors the topic online/ping handshake and handles both startup races WITHOUT a goroutine:

• core already up → the immediate send is received and acked.
• core comes up later → the core announces `gothic:core:online` on boot; this module's online listener re-sends the registration until it is acked.

Asyncify safety is a TWO-SIDED contract. This side (outbound register) wraps every dispatch in queueMicrotask (like the topic bus's __gothicDispatchAsync) so the register fires from a clean call stack, never from inside this module's running scheduler turn. The RETURN side (the core's ack + online announce) is symmetric: the full-Go core schedules those on its own microtask (see pkg/wasm/core-runtime scheduleDispatch), so the ack that lands here does NOT re-enter this component's asyncify turn.

Generated code only (like GothicRegisterSchema / the Broadcast*/Listen* helpers); it is never hand-written in a ClientSideState block, so it carries no user-facing stub-parity obligation (its host no-op lives in events_stub.go).

func HexDecode ¶

func HexDecode(s string) []byte

func HexEncode ¶

func HexEncode(src []byte) string

func ListenTopicCoreOnline ¶

func ListenTopicCoreOnline(key string, fn func())

ListenTopicCoreOnline registers a handler for the core's per-key online ack (gothic:core:topic-online:<key>). The core dispatches it AFTER replaying the topic's current per-field state to this consumer, so by the time the handler runs the per-field ListenTopicEventField handlers have already applied the replayed values. The generated consumer uses it to flip _online and flush any pending whole-struct Set (fanned out per-field).

Like the other topic listeners it re-establishes the registering scope (scopedListener) because the ack fires from an async document-event turn where findScope() cannot see the component's [data-gothic-scope], and routes through addScopedDocListener so the per-scope teardown can remove it on unmount.

func ListenTopicEvent ¶

func ListenTopicEvent(keyName string, fn func(string))

ListenTopicEvent registers a cross-module listener for topic updates.

The listener re-establishes the scope that registered it (see scopedListener) because the topic CustomEvent fires from an async turn where findScope() cannot see the component's [data-gothic-scope]; fn typically drives scoped DOM helpers via ApplyExternal → Observe, which must resolve to this scope.

func ListenTopicEventField ¶

func ListenTopicEventField(keyName, fieldName string, fn func([]byte))

ListenTopicEventField subscribes to per-field broadcasts from the core hub.

fn receives the raw frame as []byte (not string): this is the HOT consumer data-plane path (one call per broadcast per subscribed field). Passing []byte lets the generated consumer feed the pooled scratch buffer straight into NewDecoder, eliminating the string(dst)→[]byte(detail) double copy the old func(string) signature forced. Combined with the per-listener scratch reuse in topicViewInto, a stable-payload rebroadcast now allocates ZERO transient frame bytes on the receive side — the fix for the multi-MB linear-memory ratchet on TinyGo's no-shrink conservative heap. The []byte is only valid for the duration of fn (it aliases the reused scratch); the decoder copies out its own values.

func ListenTopicOnline ¶

func ListenTopicOnline(keyName string, fn func(string))

ListenTopicOnline registers a handler that receives the manager's online ack with current state. Fires once on manager startup and on every ping response.

func ListenTopicPing ¶

func ListenTopicPing(keyName string, fn func())

ListenTopicPing registers a handler for incoming pings on the topic manager WASM.

func ListenTopicSetReq ¶

func ListenTopicSetReq(keyName string, fn func(string))

ListenTopicSetReq registers a handler for incoming set-requests on a topic manager WASM.

func ListenTopicSetReqField ¶

func ListenTopicSetReqField(keyName, fieldName string, fn func(string))

ListenTopicSetReqField subscribes to per-field set-requests (used by the manager).

func LocalStorageGet ¶

func LocalStorageGet(key string) string

func LocalStorageRemove ¶

func LocalStorageRemove(key string)

func LocalStorageSet ¶

func LocalStorageSet(key, value string)

LocalStorage helpers

func Navigate ¶

func Navigate(url string)

Navigation helpers.

func OnUnmount ¶

func OnUnmount(fn func())

OnUnmount registers a cleanup callback invoked by the bootstrap's per-scope teardown when this component's [data-gothic-scope] element is removed from the DOM. Use it to release things created outside the component's own subtree (persistent document listeners attached directly, timers, topic mounts). The callback is stored at __gothic_registry[<scope>].__onUnmount and retained in keep so TinyGo's GC won't reclaim it before teardown fires.

func PingTopicManager ¶

func PingTopicManager(keyName string)

PingTopicManager dispatches a ping to the topic manager asking for an online ack.

func PingUntilOnline ¶

func PingUntilOnline(keyName string, isOnline func() bool)

PingUntilOnline retries PingTopicManager every 50 ms until isOnline returns true. Runs in its own goroutine so it doesn't block the caller.

A goroutine does not inherit the scope carrier across suspension points, so we CaptureScope() at spawn and RunInScope() each iteration to re-establish the caller's scope (isOnline may read scoped state). For a single-scope instance the captured scope is bootstrapScope, so behaviour is unchanged.

func PushState ¶

func PushState(url, title string)

func ReadTopicStore ¶

func ReadTopicStore(keyName string) (string, bool)

ReadTopicStore reads the encoded topic value from the shared JS store.

func RegisterTopicWithCore ¶

func RegisterTopicWithCore(key string, fields []string)

RegisterTopicWithCore performs the topic → core control-plane registration. The CustomEvent detail is a plain JS object {key, fields:[...]} — control-plane JSON/values, NEVER binary. It hands the core the topic's wire key and the ORDERED field-name list so the core can subscribe to each gothic:topic-req:<key>:<field> and replay the current per-field state back. The field names are ROUTING metadata; the core still never interprets a payload byte (the generic interpreter is DEFERRED), so this keeps the core opaque.

Startup races are handled the same way as GothicRegisterWithCore, with no goroutine:

• core already up → the register is received; the core replays this topic's stored per-field frames and announces the per-key online ack.
• core comes up later → it announces gothic:core:online on boot; this re-fires the register until the per-key online ack lands (acked short-circuits, so at most one extra send per core boot).

Every dispatch is wrapped in queueMicrotask so it leaves a clean call stack and never fires from inside this module's running asyncify turn (the RETURN side — the core's replay + ack — is symmetric: the full-Go core microtask-schedules those, so nothing re-enters this component's scheduler).

func Reload ¶

func Reload()

func RemoveClass ¶

func RemoveClass(id, className string)

func RemoveElement ¶

func RemoveElement(el JSValue)

func RequestTopicSet ¶

func RequestTopicSet(keyName, encoded string)

RequestTopicSet dispatches a set-request to the topic manager WASM for this key. The manager is the sole writer: it applies the update and broadcasts back.

func RequestTopicSetField ¶

func RequestTopicSetField(keyName, fieldName, encoded string)

RequestTopicSetField sends a per-field set-request to the manager. Event name: "gothic:topic-req:<keyName>:<fieldName>"

func RequestTopicSetFieldBytes ¶

func RequestTopicSetFieldBytes(keyName, fieldName string, b []byte)

RequestTopicSetFieldBytes is RequestTopicSetField for callers that already hold the encoded frame as []byte (the generated consumer's _broadcastAll). It hands the bytes straight to dispatchDirect — which copies them into dispatchHold — skipping the string(encoded)→[]byte(encoded) round-trip the string form forces on every per-field send. Event name is identical: "gothic:topic-req:<keyName>:<fieldName>".

func RunInScope ¶

func RunInScope(id string, fn func())

RunInScope runs fn with the given scope active, restoring the previous scope afterwards. Pair it with CaptureScope to carry a scope into a goroutine or deferred callback. Nesting is supported.

func SessionStorageGet ¶

func SessionStorageGet(key string) string

func SessionStorageRemove ¶

func SessionStorageRemove(key string)

func SessionStorageSet ¶

func SessionStorageSet(key, value string)

SessionStorage helpers

func SetAttr ¶

func SetAttr(id, attr, value string)

func SetHTML ¶

func SetHTML(id, html string)

func SetStyle ¶

func SetStyle(id, property, value string)

func SetText ¶

func SetText(id, value string)

func SetValue ¶

func SetValue(id, value string)

func ToggleClass ¶

func ToggleClass(id, className string)

func TriggerDownload ¶

func TriggerDownload(filename string, data []byte, mimeType string)

TriggerDownload prompts the browser to download `data` as a file named `filename` with the given MIME type.

func UpdateTopicOnlineStore ¶

func UpdateTopicOnlineStore(keyName string, encoded []byte)

UpdateTopicOnlineStore updates the JS-side topic store so that late-joining consumers see fresh data via ReadTopicStore, WITHOUT dispatching the gothic:topic-online event. Use this from ListenTopicSetReq to fix the startup race (T5) without triggering ListenTopicOnline scans in already-running consumers.

func WriteClipboard ¶

func WriteClipboard(text string)

WriteClipboard writes the given text to the system clipboard via navigator.clipboard.writeText.