// TriggerAction dispatches the action to the matching controller

// method on every connection in the session group, then sends the

// updated template to each of those connections.

//

// This behaves identically to client-initiated actions: the action

// runs through the controller's action method, errors are captured,

// and diffs are sent over WebSocket to each connection.

//

// Example:

// session.TriggerAction("tick", nil)

// session.TriggerAction("new_notification", map[string]interface{}{"id": 123})

TriggerAction(action string, data map[string]interface{}) error

http.Handler

// Shutdown gracefully shuts down the handler, draining connections.

//

// It performs the following steps:

// 1. Stops accepting new WebSocket connections

// 2. Sends close frames to all active WebSocket connections

// 3. Waits for in-flight requests to complete (respecting context timeout)

//

// The context timeout controls how long to wait for connections to close.

// After the timeout, remaining connections are forcefully closed.

//

// Example usage with http.Server:

// ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)

// defer cancel()

// handler.Shutdown(ctx)

// server.Shutdown(ctx)

Shutdown(ctx context.Context) error

// MetricsHandler returns an http.Handler that exports Prometheus metrics.

//

// The handler responds to GET requests with metrics in Prometheus text format.

// Typically mounted at /metrics for scraping by Prometheus.

//

// Example with standard library http mux:

// mux := http.NewServeMux()

// handler := template.Handle(store)

// mux.Handle("/live", handler)

// mux.Handle("/metrics", handler.MetricsHandler())

// http.ListenAndServe(":8080", mux)

//

// Example with gorilla/mux:

// r := mux.NewRouter()

// handler := template.Handle(store)

// r.Handle("/live", handler)

// r.Handle("/metrics", handler.MetricsHandler())

MetricsHandler() http.Handler

Template *Template

Controller interface{} // Singleton controller with dependencies

State State // Initial state template (cloned per session)

Upgrader WSUpgrader

SessionStore SessionStore

Authenticator Authenticator

PubSubBroadcaster pubsub.Broadcaster // Optional: for distributed broadcasting across instances

AllowedOrigins []string

WebSocketDisabled bool

MaxConnections int64 // Maximum total connections (0 = unlimited)

MaxConnectionsPerGroup int64 // Maximum connections per group (0 = unlimited)

CookieMaxAge time.Duration // Session cookie max age (default: 1 year)

UploadConfigs map[string]uploadtypes.UploadConfig // Upload field configurations

wsBufferSize int // WebSocket send buffer size per connection (default: 50)

ProgressiveEnhancement bool // Enable non-JS form submission support with PRG pattern (default: true)

HasSync bool // Controller implements Sync() lifecycle method (detected once at Handle() time via reflection, not per-request)

Capabilities []string // Controller capabilities detected at setup (e.g., ["change"])

config mountConfig

persistable persistableState // non-nil if state has lvt:"persist" fields

registry *session.ConnectionRegistry

limits *session.ConnectionLimits

metricsExporter *observe.PrometheusExporter

tempFileManager uploadTempFileManager

httpTemplates sync.Map // groupID → *httpTemplateCacheEntry (cached for HTTP POST diff optimization)

httpLastPaths sync.Map // groupID → string (last served request path, for detecting URL changes)

// Graceful shutdown state

shutdownOnce sync.Once

shutdownChan chan struct{}

shutdownWg sync.WaitGroup

isShutdown atomic.Bool

mu sync.Mutex

tmpl *Template

lastAccessed atomic.Int64 // unix timestamp, for time-based eviction in ephemeral mode

state interface{} // Typed state (cloned per session)

messages map[string]string // Unified map: field errors + flash (prefixed with "_flash:")

messagesMu sync.RWMutex // Mutex for thread-safe message access

groupID string // Session/group ID for this connection

c.messagesMu.Lock()

defer c.messagesMu.Unlock()

c.messages[field] = message

c.messagesMu.Lock()

defer c.messagesMu.Unlock()

// Clear field errors but preserve flash messages for the upcoming render.

// Flash messages are cleared separately after the response is sent.

newMessages := make(map[string]string)

for k, v := range c.messages {

if strings.HasPrefix(k, lvtcontext.FlashPrefix) {

newMessages[k] = v

}

}

c.messages = newMessages

c.messagesMu.RLock()

defer c.messagesMu.RUnlock()

// Return copy to avoid race conditions

result := make(map[string]string, len(c.messages))

for k, v := range c.messages {

result[k] = v

}

return result

// Validate key: reject keys with ":" or starting with "_"

if strings.Contains(key, ":") || strings.HasPrefix(key, "_") {

slog.Warn("Invalid flash key ignored",

slog.String("component", "live_handler"),

slog.String("key", key),

slog.String("reason", "keys must not contain ':' or start with '_'"))

return

}

c.messagesMu.Lock()

defer c.messagesMu.Unlock()

c.messages[lvtcontext.FlashPrefix+key] = message

c.messagesMu.Lock()

defer c.messagesMu.Unlock()

// Only clear flash messages (preserve errors)

newMessages := make(map[string]string)

for k, v := range c.messages {

if !strings.HasPrefix(k, lvtcontext.FlashPrefix) {

newMessages[k] = v

}

}

c.messages = newMessages

c.messagesMu.RLock()

defer c.messagesMu.RUnlock()

vals := url.Values{}

for k, v := range c.messages {

if strings.HasPrefix(k, lvtcontext.FlashPrefix) {

vals.Set(strings.TrimPrefix(k, lvtcontext.FlashPrefix), v)

}

}

return vals

c.messagesMu.RLock()

defer c.messagesMu.RUnlock()

for k := range c.messages {

if !strings.HasPrefix(k, lvtcontext.FlashPrefix) {

return true

}

}

return false

c.messagesMu.RLock()

defer c.messagesMu.RUnlock()

result := make(map[string]string)

for k, v := range c.messages {

if !strings.HasPrefix(k, lvtcontext.FlashPrefix) {

result[k] = v

}

}

return result

// Add header to indicate WebSocket availability

if h.config.WebSocketDisabled {

w.Header().Set("X-LiveTemplate-WebSocket", "disabled")

} else {

w.Header().Set("X-LiveTemplate-WebSocket", "enabled")

}

if WSIsUpgrade(r) {

if h.config.WebSocketDisabled {

http.Error(w, "WebSocket is disabled on this endpoint", http.StatusBadRequest)

return

}

h.handleWebSocket(w, r)

} else {

h.handleHTTP(w, r)

}

// Check if shutting down - reject new connections

if h.isShutdown.Load() {

http.Error(w, "Service is shutting down", http.StatusServiceUnavailable)

return

}

// Track this connection goroutine for graceful shutdown

h.shutdownWg.Add(1)

defer h.shutdownWg.Done()

// Authenticate user and get session group

userID, err := h.config.Authenticator.Identify(r)

if err != nil {

slog.Error("Authentication failed",

slog.String("component", "live_handler"),

slog.Any("error", err))

h.writeUnauthorized(w)

return

}

groupID, err := h.config.Authenticator.GetSessionGroup(r, userID)

if err != nil {

slog.Error("Failed to get session group",

slog.String("component", "live_handler"),

slog.Any("error", err))

http.Error(w, "Internal server error", http.StatusInternalServerError)

return

}

// Check connection limits before upgrading

if !h.limits.CanAccept(groupID) {

stats := h.limits.Stats()

slog.Warn("Connection rejected (at capacity)",

slog.String("component", "live_handler"),

slog.Int64("active", stats.ActiveConnections),

slog.Int64("max", stats.MaxConnections),

slog.String("group_id", groupID),

slog.Int64("group_count", h.limits.GroupConnectionCount(groupID)),

slog.Int64("max_per_group", stats.MaxPerGroup))

http.Error(w, "Service at capacity, please try again later", http.StatusServiceUnavailable)

return

}

// Set session cookie if this is a new session (cookie doesn't exist)

setCookieIfNew(w, r, groupID, h.config.CookieMaxAge)

// Upgrade to WebSocket after authentication and limit check succeeds

conn, err := h.config.Upgrader.Upgrade(w, r, nil)

if err != nil {

slog.Error("WebSocket upgrade failed",

slog.String("component", "live_handler"),

slog.Any("error", err))

return

}

defer func() {

if err := conn.Close(); err != nil {

slog.Warn("WebSocket close error",

slog.String("component", "live_handler"),

slog.Any("error", err))

}

}()

// Acquire connection slot (increment counters)

if err := h.limits.Acquire(groupID); err != nil {

slog.Error("Failed to acquire connection slot",

slog.String("component", "live_handler"),

slog.Any("error", err))

if writeErr := conn.WriteMessage(WSCloseMessage, WSFormatCloseMessage(WSCloseServiceRestart, "Service at capacity")); writeErr != nil {

slog.Warn("Failed to send close message",

slog.String("component", "live_handler"),

slog.Any("error", writeErr))

}

return

}

defer h.limits.Release(groupID)

slog.Info("Client connected",

slog.String("component", "live_handler"),

slog.String("user_id", userID),

slog.String("group_id", groupID),

slog.String("remote_addr", r.RemoteAddr),

slog.Int64("active_connections", h.limits.ActiveConnections()))

// Clone template for this connection to avoid state conflicts

// Each WebSocket connection needs its own template instance because

// ExecuteUpdates() tracks state (lastTree, lastData, etc.)

connTmpl, err := h.config.Template.Clone()

if err != nil {

slog.Error("Failed to clone template",

slog.String("component", "live_handler"),

slog.Any("error", err))

return

}

// Get or create state for this session group.

// If persist fields exist, try to restore them from SessionStore.

// Otherwise, always start with a fresh clone (ephemeral).

ctx := r.Context()

var typedState interface{}

if restored, ok := h.restorePersistedState(ctx, groupID); ok {

typedState = restored

} else {

typedState, err = h.cloneStateTyped()

if err != nil {

slog.Error("Failed to clone state",

slog.String("component", "live_handler"),

slog.Any("error", err))

return

}

if h.persistable == nil {

slog.Debug("Using fresh state (no persist fields)",

slog.String("component", "live_handler"),

slog.String("group_id", groupID))

} else {

slog.Info("Created new session group",

slog.String("component", "live_handler"),

slog.String("group_id", groupID))

}

}

// Initialize upload registry for this connection

uploadRegistry := h.newUploadRegistry()

for name, config := range h.config.UploadConfigs {

if err := uploadRegistry.CreateUpload(name, config); err != nil {

slog.Warn("Failed to create upload",

slog.String("component", "live_handler"),

slog.String("upload_name", name),

slog.Any("error", err))

}

}

connTmpl.SetUploadRegistry(uploadRegistry)

// Create Connection and register in registry

connection := &session.Connection{

Conn: conn,

GroupID: groupID,

UserID: userID,

Template: connTmpl,

Stores: typedState, // Store typed state for broadcasting

Uploads: uploadRegistry,

}

h.registry.Register(connection, h.config.wsBufferSize)

defer h.registry.Unregister(connection)

defer func() {

if h.tempFileManager == nil {

return

}

if err := h.tempFileManager.RemoveSession(groupID); err != nil {

slog.Warn("Failed to clean up temp files",

slog.String("component", "live_handler"),

slog.String("group_id", groupID),

slog.Any("error", err))

}

}()

slog.Debug("Registered connection",

slog.String("component", "live_handler"),

slog.Int("total_connections", h.registry.Count()),

slog.Int("total_groups", h.registry.GroupCount()))

// Subscribe to scoped pub/sub channels for cross-instance broadcasting

if ds, ok := h.config.PubSubBroadcaster.(pubsub.DynamicSubscriber); ok {

if err := ds.SubscribeToGroup(groupID); err != nil {

slog.Warn("Failed to subscribe to group channel",

slog.String("component", "live_handler"),

slog.String("group_id", groupID),

slog.Any("error", err))

}

if gas, ok := h.config.PubSubBroadcaster.(pubsub.GroupActionSubscriber); ok {

if err := gas.SubscribeToGroupAction(groupID); err != nil {

slog.Warn("Failed to subscribe to group action channel",

slog.String("component", "live_handler"),

slog.String("group_id", groupID),

slog.Any("error", err))

}

}

if userID != "" {

if err := ds.SubscribeToUser(userID); err != nil {

slog.Warn("Failed to subscribe to user channel",

slog.String("component", "live_handler"),

slog.String("user_id", userID),

slog.Any("error", err))

}

if err := ds.SubscribeToServerAction(userID); err != nil {

slog.Warn("Failed to subscribe to server action channel",

slog.String("component", "live_handler"),

slog.String("user_id", userID),

slog.Any("error", err))

}

}

}

// Create connection state (messages are per-connection, not shared)

connSt := &connState{

state: typedState,

messages: make(map[string]string),

groupID: groupID,

}

// Create context for lifecycle methods with query params from initial connection

wsQueryData := send.QueryParamsToData(r)

lifecycleCtx := NewContext(context.Background(), "", wsQueryData)

lifecycleCtx = lifecycleCtx.WithUserID(userID)

lifecycleCtx = lifecycleCtx.WithFlashSetter(connSt)

lifecycleCtx = lifecycleCtx.WithSession(newLocalSession(h, groupID))

// Call Mount on every WebSocket connect (new session AND reconnect).

// Mount() refreshes state from the database, ensuring actions always

// work with fresh data. Keep Mount cheap — it runs on every connect.

newState, err := callMount(h.config.Controller, connSt.state, lifecycleCtx)

if err != nil {

slog.Error("Mount failed",

slog.String("component", "live_handler"),

slog.Any("error", err))

return

}

connSt.state = newState

h.persistState(ctx, groupID, connSt.state)

// Call OnConnect lifecycle method

newState, err = callOnConnect(h.config.Controller, connSt.state, lifecycleCtx)

if err != nil {

slog.Warn("OnConnect failed",

slog.String("component", "live_handler"),

slog.Any("error", err))

// Continue anyway - OnConnect errors are non-fatal

} else {

connSt.state = newState

}

// Schedule OnDisconnect call when WebSocket closes

defer callOnDisconnect(h.config.Controller)

// Send initial tree

var buf bytes.Buffer

err = connTmpl.ExecuteUpdates(&buf, connSt.state, connSt.getMessages())

if err != nil {

slog.Error("Failed to generate initial tree",

slog.String("component", "live_handler"),

slog.Any("error", err))

return

}

var tree map[string]interface{}

if err := json.Unmarshal(buf.Bytes(), &tree); err != nil {

slog.Error("Failed to parse initial tree",

slog.String("component", "live_handler"),

slog.Any("error", err))

return

}

response := UpdateResponse{

Tree: tree,

Meta: &ResponseMetadata{

Success: !connSt.hasErrors(),

Errors: connSt.getErrorsOnly(),

Capabilities: h.config.Capabilities,

},

}

responseBytes, err := json.Marshal(response)

if err != nil {

slog.Error("Failed to marshal initial response",

slog.String("component", "live_handler"),

slog.Any("error", err))

return

}

if err = writeUpdateWebSocket(connection, responseBytes); err != nil {

slog.Error("Failed to send initial tree",

slog.String("component", "live_handler"),

slog.Any("error", err))

return

}

// Create rate limiter for this connection (prevents DoS attacks)

var limiter *rate.Limiter

if h.config.Template.config.MessageRateLimit > 0 {

burst := h.config.Template.config.MessageRateBurst

if burst < 1 {

burst = 1

}

limiter = rate.NewLimiter(rate.Limit(h.config.Template.config.MessageRateLimit), burst)

}

// Start readPump goroutine: reads from WebSocket and sends to readChan.

// This decouples WebSocket reads from state mutations, allowing the event

// loop to also process broadcast dispatches via DispatchChan.

// Buffer of 1: deliberately serializes client messages with dispatch processing.

// During dispatch handling, the readPump blocks after buffering one message.

// This bounds memory and ensures state mutations are strictly sequential.

// Tradeoff: slow dispatched actions (e.g., DB calls) pause client message processing.

// Increasing the buffer would NOT help — state mutations must still be sequential.

readChan := make(chan wsReadMessage, 1)

go func() {

defer close(readChan)

for {

_, data, err := conn.ReadMessage()

// If both readChan and Done are ready, Go's select may pick Done,

// discarding the error. The event loop still exits via readChan close.

select {

case readChan <- wsReadMessage{data: data, err: err}:

case <-connection.Done():

return

}

if err != nil {

return

}

}

}()

// Event loop: processes both client messages (readChan) and

// broadcast action dispatches (DispatchChan) serially.

// All state mutations happen in this single goroutine — no mutex needed.

eventLoop:

for {

select {

case rm, ok := <-readChan:

if !ok {

break eventLoop

}

if rm.err != nil {

if WSIsUnexpectedCloseError(rm.err, WSCloseGoingAway, WSCloseAbnormalClosure) {

slog.Warn("WebSocket error",

slog.String("component", "live_handler"),

slog.Any("error", rm.err))

}

break eventLoop

}

// Rate limiting check

if limiter != nil && !limiter.Allow() {

errorResp := UpdateResponse{

Tree: nil,

Meta: &ResponseMetadata{

Success: false,

Errors: map[string]string{"_rate_limit": "Too many requests. Please slow down."},

},

}

if respBytes, err := json.Marshal(errorResp); err == nil {

_ = writeUpdateWebSocket(connection, respBytes)

}

continue

}

// Parse message

msg, err := parseActionFromWebSocket(rm.data)

if err != nil {

slog.Warn("Failed to parse message",

slog.String("component", "live_handler"),

slog.Any("error", err))

continue

}

// Check if this is an upload-related action

uploadHandled, err := h.handleUploadAction(r.Context(), conn, rm.data, msg, connSt, uploadRegistry, connection)

if err != nil {

slog.Warn("Upload action error",

slog.String("component", "live_handler"),

slog.Any("error", err))

continue

}

if uploadHandled {

continue

}

// Route forms without explicit action to the conventional Submit() method.

applyDefaultAction(&msg)

// Clear previous errors

connSt.clearErrors()

// Create Context for action dispatch.

// Note: Query params from initial WS connection are NOT included here.

// They're already available in Mount/OnConnect via wsQueryData.

// WebSocket actions use only msg.Data from the client message.

actionCtx := NewContext(r.Context(), msg.Action, msg.Data)

actionCtx = actionCtx.WithUserID(userID)

actionCtx = actionCtx.WithUploads(uploadRegistry)

actionCtx = actionCtx.WithFlashSetter(connSt)

actionCtx = actionCtx.WithSession(newLocalSession(h, groupID))

// Dispatch action using Controller+State pattern

newState, actionErr := DispatchWithState(h.config.Controller, connSt.state, actionCtx)

if actionErr != nil {

// Handle errors

switch e := actionErr.(type) {

case FieldError:

connSt.setError(e.Field, e.Message)

case MultiError:

for _, fieldErr := range e {

connSt.setError(fieldErr.Field, fieldErr.Message)

}

default:

if !errors.Is(actionErr, ErrMethodNotFound) {

connSt.setError("_general", actionErr.Error())

}

}

} else {

connSt.state = newState

}

if actionErr == nil {

h.persistState(r.Context(), groupID, connSt.state)

connection.Stores = connSt.state

h.processBroadcastsAndSync(groupID, connection, actionCtx.pendingBroadcasts())

}

// Generate tree update

buf.Reset()

if err = connTmpl.ExecuteUpdates(&buf, connSt.state, connSt.getMessages()); err != nil {

slog.Error("Template update execution failed",

slog.String("component", "live_handler"),

slog.Any("error", err))

continue

}

var tree map[string]interface{}

if err := json.Unmarshal(buf.Bytes(), &tree); err != nil {

slog.Error("Failed to parse tree",

slog.String("component", "live_handler"),

slog.Any("error", err))

continue

}

response := UpdateResponse{

Tree: tree,

Meta: &ResponseMetadata{

Success: !connSt.hasErrors(),

Errors: connSt.getErrorsOnly(),

Action: msg.Action,

},

}

responseBytes, err := json.Marshal(response)

if err != nil {

slog.Error("Failed to marshal response",

slog.String("component", "live_handler"),

slog.Any("error", err))

continue

}

if err = writeUpdateWebSocket(connection, responseBytes); err != nil {

slog.Error("WebSocket write failed",

slog.String("component", "live_handler"),

slog.Any("error", err))

break eventLoop

}

// Clear flash messages after successful render (flash shows once per action)

connSt.clearFlash()

case req := <-connection.DispatchChan:

h.handleDispatchedAction(connSt, connection, req, userID)

}

}

slog.Info("Client disconnected",

slog.String("component", "live_handler"),

slog.String("user_id", userID),

slog.String("group_id", groupID),

slog.Int("remaining_connections", h.registry.Count()))

accept := r.Header.Get("Accept")

if accept == "" {

return false

}

// Parse the Accept header and consider only the first meaningful media range.

// This avoids treating browsers that primarily prefer text/html as JSON clients

// when they include application/json as a secondary option.

for _, part := range strings.Split(accept, ",") {

mt := strings.TrimSpace(part)

if mt == "" {

continue

}

// Strip any parameters (e.g. ";q=0.9").

if semi := strings.Index(mt, ";"); semi != -1 {

mt = strings.TrimSpace(mt[:semi])

}

// Ignore wildcard entries like "*/*".

if mt == "*/*" {

continue

}

// Treat explicit JSON types (including +json subtypes) as JSON.

return mt == "application/json" || strings.HasSuffix(mt, "+json")

}

return false

// Check if cookie already exists

if cookie, err := r.Cookie("livetemplate-id"); err == nil && cookie.Value == groupID {

// Cookie exists and matches - no need to set again

return

}

// Set session cookie

http.SetCookie(w, &http.Cookie{

Name: "livetemplate-id",

Value: groupID,

Path: "/",

HttpOnly: true,

SameSite: http.SameSiteLaxMode,

MaxAge: int(cookieMaxAge.Seconds()),

})

// Handle HEAD request for capability check

if r.Method == http.MethodHead {

return

}

// Authenticate user and get session group

userID, err := h.config.Authenticator.Identify(r)

if err != nil {

slog.Error("HTTP authentication failed",

slog.String("component", "live_handler"),

slog.Any("error", err))

h.writeUnauthorized(w)

return

}

groupID, err := h.config.Authenticator.GetSessionGroup(r, userID)

if err != nil {

slog.Error("Failed to get session group for HTTP",

slog.String("component", "live_handler"),

slog.Any("error", err))

http.Error(w, "Internal server error", http.StatusInternalServerError)

return

}

// Set session cookie if this is a new session

setCookieIfNew(w, r, groupID, h.config.CookieMaxAge)

// Get or create state for this session group

ctx := r.Context()

isNewSession := false

var typedState interface{}

// Detect URL path change on GET requests to reset stale cached state

// (e.g., page-mode navigation from /posts/alpha to /posts/beta).

// POST requests are excluded — they target actions, not page navigations.

// Paths are normalized via path.Clean to treat /a/ and /a as identical.

currentPath := path.Clean(r.URL.Path)

if currentPath == "." {

currentPath = "/"

}

// Asset requests (favicon.ico, manifest.json, etc.) that hit catch-all

// handlers are not page navigations and must not trigger pathChanged.

isAssetRequest := isKnownAssetExt(path.Ext(currentPath))

pathChanged := false

if h.persistable != nil && r.Method == http.MethodGet && !isAssetRequest {

if prev, loaded := h.httpLastPaths.Load(groupID); loaded {

pathChanged = prev.(string) != currentPath

}

}

if pathChanged {

// Path changed — use fresh state for the new URL (persist fields reset).

typedState, err = h.cloneStateTyped()

if err != nil {

slog.Error("Failed to clone per-request state",

slog.String("component", "live_handler"),

slog.Any("error", err))

http.Error(w, "Internal server error", http.StatusInternalServerError)

return

}

isNewSession = true

h.httpTemplates.Delete(groupID)

slog.Debug("Refreshing session for new URL path",

slog.String("component", "live_handler"),

slog.String("group_id", groupID),

slog.String("path", currentPath))

} else if restored, ok := h.restorePersistedState(ctx, groupID); ok {

typedState = restored

slog.Debug("Using existing session group",

slog.String("component", "live_handler"),

slog.String("group_id", groupID))

} else {

// No stored state or no persist fields — start fresh

typedState, err = h.cloneStateTyped()

if err != nil {

slog.Error("Failed to clone state",

slog.String("component", "live_handler"),

slog.Any("error", err))

http.Error(w, "Internal server error", http.StatusInternalServerError)

return

}

if h.persistable == nil {

// No persist fields — ephemeral mode.

// On GET, delete cached template so first render sends full statics.

// On POST, keep cache so responses are incremental diffs.

if r.Method == http.MethodGet {

h.httpTemplates.Delete(groupID)

}

} else {

isNewSession = true

h.httpTemplates.Delete(groupID)

slog.Info("Created new session group",

slog.String("component", "live_handler"),

slog.String("group_id", groupID))

}

}

// Create connection state (messages are per-request)

connSt := &connState{

state: typedState,

messages: make(map[string]string),

groupID: groupID,

}

// Create lifecycle context with query params

queryData := send.QueryParamsToData(r)

lifecycleCtx := NewContext(ctx, "", queryData)

lifecycleCtx = lifecycleCtx.WithUserID(userID)

lifecycleCtx = lifecycleCtx.WithFlashSetter(connSt)

lifecycleCtx = lifecycleCtx.WithSession(newLocalSession(h, groupID))

// Read flash messages from cookie (set by POST redirect)

if flashCookie, err := r.Cookie("lvt-flash"); err == nil && flashCookie.Value != "" {

if flashValues, err := url.ParseQuery(flashCookie.Value); err == nil {

for key, values := range flashValues {

if len(values) > 0 {

connSt.setFlash(key, values[0])

}

}

}

// Clear cookie immediately (one-time read)

http.SetCookie(w, &http.Cookie{

Name: "lvt-flash",

Value: "",

Path: "/",

MaxAge: -1,

})

}

isHTTPGet := r.Method == http.MethodGet && !isAssetRequest

isPageRequest := !isAssetRequest

if isNewSession || isPageRequest {

newState, err := callMount(h.config.Controller, connSt.state, lifecycleCtx)

if err != nil {

// httpLastPaths still holds the previous path (Store is deferred

// until after success), so retries naturally re-detect the change.

slog.Error("Mount failed",

slog.String("component", "live_handler"),

slog.Any("error", err))

http.Error(w, "Failed to initialize application state", http.StatusInternalServerError)

return

}

connSt.state = newState

// Persist after Mount on GET/new-session only. On POST the action handler

// will persist after the action succeeds, avoiding a redundant Set.

if isNewSession || isHTTPGet {

h.persistState(ctx, groupID, connSt.state)

}

// Commit path after successful Mount (not before, to allow retries).

// Skip when no persist fields — pathChanged is never checked.

if isHTTPGet && h.persistable != nil {

h.httpLastPaths.Store(groupID, currentPath)

}

}

// Handle GET request

if r.Method == http.MethodGet {

if wantsJSON(r) {

// JS client in HTTP mode: return initial tree as JSON

httpTmpl, cloneErr := h.config.Template.Clone()

if cloneErr != nil {

http.Error(w, "Failed to clone template", http.StatusInternalServerError)