live

type AnonymousIdentity struct{}

type App[S any, I IIdentity] struct {
	// contains filtered or unexported fields
}

type Bind struct {
	// Fields are static values sent with every occurrence of this binding's
	// event, in addition to whatever the element itself contributes.
	Fields map[string]string
	// Debounce delays sending until THIS binding's DOM event has been quiet
	// for this long. Zero means no debounce.
	Debounce time.Duration
	// Throttle sends at most one of THIS binding's events per interval. Zero
	// means no throttle.
	Throttle time.Duration
	// Keys restricts a keyboard binding to these keys, and raises no event for
	// any other. Empty is every key, which is what a keydown binding without
	// this option has always meant.
	//
	// Each entry is compared, exactly and case-sensitively, against the
	// browser's own KeyboardEvent.key value: "Escape" and not "Esc",
	// "ArrowUp" and not "Up", " " and not "Space", "A" and not "a" for a
	// shifted letter. Nothing is normalised, because "a" and "A" are different
	// keys and the name set belongs to the UI Events specification rather than
	// to this library — an unrecognised name is therefore not an error here,
	// it is a filter that matches nothing, and it shows up as a binding that
	// never fires on the first keypress.
	//
	// The key is compared and the modifier state is not — unless the binding
	// also sets NoModifiers, which is the only thing that reads a modifier and
	// is off by default for the reason stated there. A printable key already
	// carries its modifiers (Shift and "=" arrive as "+"), a modifier pressed
	// alone arrives as "Shift", "Control", "Alt" or "Meta" and matches only a
	// filter that names it, and a Ctrl or Meta chord belongs to the browser:
	// this library takes no key away from the browser except where a binding
	// asked for it by name, which is PreventDefault below and is off by
	// default too.
	//
	// A key filter on an event that carries no key — a click, an input — never
	// matches, so the binding never fires. A filter filters.
	//
	// ":" and ";" separate the bindings the client parses, so a key that is
	// one of those two characters cannot be expressed here, and OnWith PANICS
	// on one rather than rendering it. Nothing else is reserved: "," and " "
	// and every other printable key value are carried through unchanged,
	// because a list of keys is emitted as one binding per key rather than as
	// a separated list.
	//
	// That list of two is complete and did not grow when Fields, Debounce and
	// Throttle moved into the binding beside this one. They are further ":"
	// components of a grammar that had already spent ":", so the set of
	// characters a key may not be is exactly what it was: ":" and ";".
	//
	// What the panic replaces is worth saying, because it is what a page
	// written before 2026-08-05 got. Such a key used to render, and rendering
	// it did something neither this comment nor the author asked for: the
	// stray separator became an extra component, so the key filter widened to
	// EVERY key and every option declared beside it landed one slot later than
	// the client reads it — a 150 ms Debounce arrived as a 150 ms Throttle. A
	// ";" was worse: it split the binding in two and left the remainder as a
	// spec of junk. Both were silent.
	//
	// It is a panic and not an error because OnWith returns templ.Attributes
	// and has no error channel — see On.
	Keys []string

	// NoModifiers restricts this binding to presses with NO modifier key
	// held — no Shift, no Control, no Alt, no Meta.
	//
	// False, the zero value, is what every key binding has meant since
	// 591c275a: the key is compared and the modifier state is not. That
	// default is not a legacy, it is required: a printable key already
	// carries its modifiers, and "+" IS Shift and "=" pressed together on
	// most layouts, so a binding that named "+" and silently demanded no
	// modifier would match nothing (F-CTR-6).
	//
	// What it reads is exactly four booleans — the event's shiftKey, ctrlKey,
	// altKey and metaKey — and any one of them held is a press this binding
	// does not match. Two consequences of that are worth naming here, because
	// neither is visible from the option's name:
	//
	//   - AltGr sets BOTH ctrlKey and altKey. So a printable key that needs
	//     AltGr on the member's layout — "@" on many European layouts, "\"
	//     and "|" on others — will NOT match a binding that names it and sets
	//     this option, while the member is typing exactly the character the
	//     binding asked for. Name such a key without this option.
	//   - CapsLock and NumLock are NOT read. They are lock states rather than
	//     held modifiers, they set none of the four booleans, and a binding
	//     filtered here fires with either of them on.
	//
	// It applies whether or not Keys is set, and it is not restricted to
	// keyboard events. An unfiltered keydown binding with this option raises
	// its event for every UNMODIFIED key, which is a filter and not a no-op;
	// and because a mouse event carries the same four booleans, a click
	// binding with this option means a plain click rather than a Ctrl+click
	// or a Shift+click — the two a browser already treats as "open this
	// somewhere else". An event that carries none of the four, such as input
	// or submit, has all four absent, so a binding on one is unaffected.
	//
	// A binding this filters out suppresses nothing and ends nothing: the
	// client goes on to the next binding on the element for the same DOM
	// event. That is what lets Enter and Shift+Enter reach two different
	// bindings, or one binding and none at all, from one composer (F-CHT-3).
	NoModifiers bool

	// PreventDefault calls preventDefault() on the browser event when THIS
	// binding matches, and only then.
	//
	// The library calls it for a recognised form submit and an anchor click
	// already; this is the same act for a binding the author declared
	// explicitly, per binding, defaulting off. It is not a filter: a binding
	// that does not match does not suppress anything, which is what leaves
	// Shift+Enter to the browser.
	//
	// It is NOT called while an IME composition is active, and that ordering
	// is load-bearing rather than incidental. Enter during a composition
	// COMMITS the candidate, so a binding that suppressed it would take the
	// commit key away from every composer that uses one — the population
	// FR-26's composition guard exists for. The client tests that guard
	// first: mid-composition it neither sends the event nor suppresses the
	// default, and the binding fires on the Enter after the commit instead.
	PreventDefault bool
}

type Config[S any, I IIdentity] struct {
	// Init is the mount hook: it produces the session's initial state and any
	// startup effects, such as a pubsub subscription. It runs once per session,
	// as the first transition, before the first snapshot.
	//
	// Optional. Nil means the zero value of S, no startup effects and no error
	// — which is the only total, side-effect-free thing an unwritten mount hook
	// could mean, and it is what an application whose sessions all start empty
	// writes out by hand. Teardown, the hook on the other end of the same
	// session, has always been optional on the same argument.
	//
	// It is the ONE field New fills in rather than refusing, and the line
	// between it and the rest is that the rest cannot be guessed: a reducer, a
	// region, the set of accepted event names and the four security hooks are
	// each something only the application knows, and a library that picked for
	// them would be picking deny-by-default's opposite. Getting this one wrong
	// is also visible on the first run rather than in production — sessions
	// start empty, and so does the page, because [App.PageHandler] renders from
	// this same hook — where a guessed origin allowlist or a guessed
	// authorization rule would not be visible at all.
	//
	// [App.PageHandler] calls it once per page request as well, to render the
	// first paint from the state a session would start at. Init is therefore a
	// loader: it must be safe to call for a read. The effects it returns are
	// performed only for a real session; on a page render they are discarded.
	// See that method.
	Init func(ctx context.Context, session Session[I]) (S, []Effect[I], error)

	// Reduce is the pure state transition. Required.
	Reduce Reducer[S, I]

	// Fragments are the server-owned live regions. Required, non-empty, and
	// every ID must be unique.
	Fragments []Fragment[S]

	// Events are the event names this application accepts. Required.
	//
	// An event whose name is not here is refused with UNKNOWN_EVENT and
	// counted, never dispatched and never ignored: unknown input is
	// default-deny. Declaring the set up front is also what bounds the
	// cardinality of the per-event metric label before the first connection.
	Events []string

	// Teardown runs after the session actor exits, with the final state, for
	// unsubscribing. Optional.
	Teardown func(ctx context.Context, session Session[I], state S)

	// Origins is the allowlist of permitted Origin values, checked on the
	// upgrade request before any per-session memory is allocated. Required
	// unless it contains AnyOrigin. Deny by default: there is no wildcard, no
	// reflection of the request's own Origin, and no pass for a request that
	// sends none.
	Origins []string

	// Authenticate derives the session identity from the upgrade request.
	// Required; use Anonymous to opt out.
	Authenticate func(request *http.Request) (I, error)

	// Authorize runs before the reducer for every event, at the single
	// mailbox ingress, so a new event kind cannot skip it. Required; use
	// AllowAll to opt out.
	//
	// Returning nil allows the event. Returning a *DenyError rejects it
	// without closing the connection. Returning a *FatalDenyError rejects it
	// and closes the connection.
	Authorize func(ctx context.Context, session Session[I], event Event) error

	// CSRF validates a token bound to the authenticated application session.
	// Required; use NoCSRFCheck to opt out.
	CSRF func(request *http.Request) error

	// Limits are the resource bounds. Any zero field takes its documented
	// default.
	Limits Limits

	// Logger is the structured log sink. Nil disables library logging and the
	// provenance log with it, which makes the reverse lookup from a captured
	// patch back to its cause unavailable. The frames still carry the causal
	// chain either way; what is lost is the server-side index.
	Logger *slog.Logger

	// Metrics enables the full metric set with one field. Nil disables it, at
	// a cost of one predictable branch per call site.
	Metrics metric.MeterProvider

	// Tracer enables the full trace set with one field. The provider is taken
	// explicitly rather than read from the OpenTelemetry global, which is what
	// lets this library depend on the trace API submodule rather than the root.
	Tracer trace.TracerProvider

	// Dev turns on developer mode. It must be false in production.
	//
	// It does three things, and nothing else.
	//
	// # 1. Panic detail in the Error frame
	//
	// In
	// production such a frame carries a fixed generic message and the causal
	// identifiers, and nothing else; with Dev set, the same frame also carries
	// the panic value and its stack. The full stack is written to Logger at
	// error level in both modes — dev mode only puts it where a developer with
	// a browser open will see it (FR-23, checklist §5.9).
	//
	// It reaches both sites that produce an Error frame: a panicking reducer,
	// and a panicking fragment render or Dirty declaration. The third site
	// FR-23 names, a panicking effect, deliberately becomes an
	// EffectFailedEvent instead of a frame, and EffectFailedErrorField already
	// carries the panic value in production and in dev alike — see that
	// constant, because it is a disclosure path this field does not gate.
	//
	// What reaches the browser is bounded: protocol.md caps an error frame's
	// message at 512 bytes, so a long stack arrives truncated. The frame is a
	// pointer into the log, not a copy of it.
	//
	// # 2. The dev session inspector (FR-44, NFR-8)
	//
	// With Dev set, App.Handler serves the inspector's JavaScript under the
	// mount and (*App).InspectorScript renders the tag that loads it. With Dev
	// false the route answers 404 and the component writes nothing, which is
	// how NFR-8's "MUST NOT load in production builds" is enforced rather than
	// asserted. The inspector is a separate artifact and costs the shipped
	// runtime nothing at all: it reads the session's frames off the WebSocket
	// and there is no seam for it anywhere in client/runtime.js.
	//
	// The library still logs no HTMX ownership violation, in either mode:
	// RFC-0001 §10.3 chose a documented precedence rule over a server-side
	// scan of rendered HTML for hx-* attributes, so there is nothing
	// server-side to detect. Flagging an hx-* element inside an unpreserved
	// live fragment is the inspector's job, in the browser, where the element
	// actually is.
	//
	// # 3. Dev reload (FR-57)
	//
	// With Dev set, App.Handler serves the dev-reload client's JavaScript and
	// the build-identity route under the mount, and (*App).DevReloadScript
	// renders the tag that loads it; with Dev false all three write nothing or
	// answer 404. A rebuilt-and-restarted process then reloads the page by
	// itself, which is the only way a change outside a live fragment — the
	// page shell, the head, a fragment whose markup moved while its state did
	// not — ever reaches a browser that is already connected.
	//
	// It preserves nothing the process itself did not preserve. See
	// DevBuildID and docs/guide/dev-reload.md, both of which say so in more
	// detail than a field comment can.
	Dev bool

	// DevBuildID overrides the identity gotth-live uses to tell one build of
	// this application from another. It is read only when Dev is set.
	//
	// Leave it empty and the identity is derived, once per process and lazily,
	// from a SHA-256 of the running executable. That default is what makes a
	// restart that rebuilt nothing — a crash loop, a `docker compose restart`,
	// a rebuild of source that did not actually change — leave the page alone
	// and let the client runtime's own reconnect restore it, instead of
	// reloading the document out from under a developer who changed nothing.
	//
	// Set it when the derived value cannot work or is not what you mean: a
	// commit hash injected with -ldflags, a container image digest, or a
	// counter your own reload loop increments. Any value works as long as it
	// CHANGES when the code changes and does not change when it does not; a
	// constant string turns dev reload off without turning Dev off.
	//
	// It is validated at New whatever Dev is set to — at most 128 bytes, no
	// control bytes, no leading or trailing whitespace — because a field
	// checked in only one mode is a field that starts failing on the deploy
	// that flips the mode. The bounds are what the value has to survive: it is
	// rendered into a script tag and returned as the entire body of the poll
	// the browser makes.
	DevBuildID string
}

type ConfigError struct {
	// Field is the Config field at fault.
	Field string
	// Detail says what to set it to.
	Detail string
}

type DenyError struct {
	// Reason is operator-facing. A generic message reaches the client in
	// production, because an authorization reason is an authorization input.
	Reason string
}

type Effect[I IIdentity] struct {
	// Source names the effect for provenance and metrics, in the form
	// "package.action" — it becomes the origin source "effect:<name>" on every
	// patch the effect causes, and it is the value a failure event reports in
	// [EffectFailedSourceField].
	//
	// It is at most the protocol's origin-source budget less the library's
	// "effect:" prefix, and must match ^[a-z][a-z0-9_.:/-]*$. A source that
	// cannot name an origin is refused before Run is called.
	Source string

	// Run performs the effect. It is called once, on a goroutine the library
	// owns and waits for at shutdown, and it is the only place in an
	// application where I/O belongs: a reducer returns this value and performs
	// nothing.
	//
	// It receives the session the effect is acting for — an effect acts on a
	// session's behalf and its identity is an input to what it does — and the
	// [Emitter] that injects the results back into that session as events. A
	// returned error becomes an [EffectFailedEvent] the reducer handles; wrap
	// it in [Retryable] to classify it as transient. A panic is contained,
	// counted, and delivered as the same failure event, classified terminal.
	//
	// Everything the effect needs beyond those three is captured: this is a
	// closure over whatever the application owns — a store, a broker, a
	// connection pool — which is what makes a central executor unnecessary and
	// is why there is no longer a Config.Execute to type-switch in.
	Run func(ctx context.Context, session Session[I], emit Emitter) error
}

type Emitter func(event Event) error

type Event struct {
	// Name is the registered event name.
	Name string
	// FragmentID is the fragment whose markup raised the event.
	FragmentID string
	// Fields are the form values the event carried.
	Fields Fields
	// At is stamped at the actor boundary. A reducer reads it here rather
	// than calling a clock, which is what makes an event log replayable.
	//
	// On an event constructed for an [Emitter] it must be left zero: the
	// boundary stamps it, and a value set here is rejected rather than
	// silently replaced.
	At time.Time

	// ID is the server-minted causal identifier, session-scoped and
	// monotonic. It is zero for the transitions the server started on its
	// own, where the origin source names the cause instead.
	//
	// It is read-only in practice. On an event constructed for an [Emitter]
	// it must be left zero, and a non-zero value is rejected with an error
	// rather than dropped: causal identifiers are minted by the server so that
	// untrusted or mistaken input cannot forge provenance, and an application
	// does not need to set one — the library carries the edge from the event
	// that scheduled an effect to the patches the effect produces, and records
	// it in the patch's contributing events.
	ID uint64

	// Contributing names events of this session whose state changes this
	// event carries, and is the one causal field an application sets rather
	// than reads. It belongs on an event constructed for an [Emitter] and is
	// ignored anywhere else.
	//
	// It exists because an asynchronous fan-out through shared state splits
	// the knowledge in two. The library knows which event scheduled an effect;
	// only the application knows which event produced the value that effect is
	// now delivering, and on a shared store those are different events — the
	// subscription was scheduled at mount, the value came from a click. Listing
	// the click here is what lets an operator holding the patch that changed
	// the number reach the interaction that changed it.
	//
	// It is a contributing claim, never a causal one: the patch's own cause
	// stays the server-minted origin, and these identifiers land in the
	// patch's contributing events beside any the library added. Naming an
	// event of another session is not possible — identifiers are
	// session-scoped — and naming the wrong one of your own is an application
	// bug rather than a way to forge provenance.
	//
	// At most 64 identifiers. The [Emitter] rejects a longer list with an
	// error naming the field and the count, so the effect learns about it and
	// the reducer sees a deterministic effect failure; it is not truncated to
	// fit, because dropping provenance to save room is the failure the
	// coalescing flush exists to prevent. The number is not configurable: the
	// patch's contributing list is bounded by the protocol, this is one event's
	// share of it, and every identifier listed here is one the library may not
	// coalesce. If more than 64 events genuinely contributed to one emission,
	// the claim being made is about the whole session rather than about this
	// value, and the provenance an operator can act on is the narrower one.
	Contributing []uint64
}

type FatalDenyError struct {
	// Reason is operator-facing, as for DenyError.
	Reason string
}

type Fields struct {
	// contains filtered or unexported fields
}

type Fragment[S any] struct {
	// ID is a stable identity matching ^[A-Za-z0-9_:.-]{1,64}$, unique within
	// an application. It is what a patch names, so changing it is a
	// client-visible change.
	ID string

	// Render produces this region's markup from state. It must be a pure
	// function of state: the same state must render byte-identical HTML,
	// across runs and across processes. The known hazard is ranging over a Go
	// map in a template; range a sorted slice instead.
	Render func(state S) templ.Component

	// Dirty optionally declares whether a transition may have changed this
	// fragment. Nil means "re-render on every transition", which is always
	// safe. Over-declaring costs a suppressed render; under-declaring is a
	// correctness bug, and livetest.AssertDirtyComplete is what catches it.
	Dirty func(prev, next S) bool

	// Children declares an ordered, session-local collection of nested regions.
	// Each child ID must start with ID + ":", be unique, and declare no children
	// of its own. Definitions remain fixed; membership is a pure projection of
	// state. Render must include every child, in this order, inside this region.
	//
	// Membership/order changes, snapshots, or this parent's Dirty returning true
	// render the complete parent. Otherwise only dirty children render and patch.
	// Set Dirty to the parent's structural projection; nil still means always.
	// Child Dirty functions receive the same previous/next application states.
	// Events may address only children in the last successfully sent render;
	// reducers must also reject members removed by a queued state transition.
	Children func(state S) []Fragment[S]
}

type ID [16]byte

type IIdentity interface {
	// Subject returns a stable, non-secret identifier, used for logging and
	// for per-identity session limits. It must not be a token.
	Subject() string
}

type Limits struct {
	// MaxInboundFrameBytes caps a decoded frame. It is applied to the
	// connection before any payload is allocated, which is what makes it the
	// authoritative inbound limit rather than a check after the fact.
	// Default 65536.
	//
	// It must be between 1024 and 1048576. The mount snapshot announces it to
	// the client, in a field the schema refines to that interval, so a value
	// outside it is a frame this library builds and then refuses to send. New
	// rejects such a value rather than starting a server every session of
	// which dies at establishment (D-23). Zero takes the default.
	MaxInboundFrameBytes int

	// MaxEventsPerSecond and EventBurst are the inbound event token bucket.
	// Defaults 50 and 100.
	MaxEventsPerSecond float64

	// EventBurst is that bucket's depth: how far a flurry of interactions may
	// run ahead of MaxEventsPerSecond before the limiter starts refusing. A
	// keystroke-per-character field is the case it is sized for.
	EventBurst int

	// MailboxDepth bounds the session's mailbox. A full mailbox rejects with a
	// typed error; it never blocks, because blocking the read pump would stall
	// the connection's own liveness detection.
	//
	// It is also a memory parameter. A Go buffered channel allocates its whole
	// backing array at make time, for the life of the channel, occupied or
	// not. Default 64.
	MailboxDepth int

	// AckChannelDepth bounds the acknowledgement channel. A full channel
	// drops, which is lossless because an acknowledgement is a cumulative
	// high-water mark: the next one supersedes the one dropped and the window
	// re-opens a round trip later. Default 32.
	AckChannelDepth int

	// AckWindow is how many unacknowledged patches may be in flight.
	// Default 16.
	//
	// It must be between 1 and 256, for the reason MaxInboundFrameBytes must:
	// the mount snapshot carries it in a refined field. Zero takes the
	// default, so the floor is reachable only as a deliberate 1.
	AckWindow int

	// CoalesceFlushAt is the size of the contributing-event union at which a
	// coalesced patch is emitted immediately rather than coalesced further, so
	// provenance is never truncated. Default 512.
	//
	// It must be between 1 and 959. The protocol bounds a patch's
	// contributing-event list at 1024 (H-4), and the frame this trigger forces
	// carries more than the trigger counted: the transition being emitted at
	// the time, on top of the ones already deferred, plus whatever the
	// application named in that event's Event.Contributing — at most 64, which
	// is the term that makes the headroom 65 rather than 1. Set above 959 the
	// flush constructs a frame the protocol refuses, and the deferred set is
	// gone by then, so the field whose purpose is to keep provenance is what
	// loses it. New rejects such a value rather than quietly substituting a
	// working one: a limit that silently becomes a different limit is not a
	// limit an operator can reason about.
	//
	// Lower is legal and meaningful — it trades more frames for smaller
	// provenance sets. Zero takes the default.
	CoalesceFlushAt int

	// MinResyncInterval and ResyncBurst are the resync budget, deliberately
	// independent of the event bucket. A resync is the one client frame that
	// triggers work proportional to the whole state. Defaults one second and 3.
	MinResyncInterval time.Duration

	// ResyncBurst is that budget's depth. It is small on purpose: a client
	// that legitimately needs a snapshot needs one, not three, and a client
	// asking repeatedly is either looping or hostile.
	ResyncBurst int

	// WriteDeadline bounds one write; exceeding it with a full window evicts.
	// Default five seconds.
	WriteDeadline time.Duration

	// SlowClientGrace is how long the outbound window may stay continuously
	// full before the session is evicted. Default thirty seconds.
	SlowClientGrace time.Duration

	// HeartbeatInterval must be below the shortest idle timeout in the network
	// path. Default twenty seconds.
	//
	// It must also be between one second and five minutes, for the reason
	// MaxInboundFrameBytes must: the mount snapshot carries it in a refined
	// field, in whole milliseconds. A sub-millisecond interval is out of range
	// however it is spelled, because the wire value is what the predicate
	// applies to.
	HeartbeatInterval time.Duration

	// HeartbeatTimeout is peer-dead detection. Default fifty seconds.
	HeartbeatTimeout time.Duration

	// IdleTimeout evicts a session with no inbound frame other than
	// heartbeats. Default thirty minutes.
	IdleTimeout time.Duration

	// EffectDrainTimeout is how long shutdown waits for in-flight effects
	// before it counts and logs the overrun. Shutdown then keeps waiting:
	// every effect is joined, so an effect must return once its context is
	// cancelled. Default five seconds.
	EffectDrainTimeout time.Duration

	// MaxSessionsPerIdentity bounds one subject's concurrent connections.
	// Default 20.
	MaxSessionsPerIdentity int

	// MaxSessions bounds the process. The default is unlimited, and operators
	// should set it.
	MaxSessions int

	// PanicBudget is how many times one site may panic within a session before
	// the session closes. Other sessions are unaffected either way. Default 3.
	PanicBudget int
}

type Reducer[S any, I IIdentity] func(state S, ev Event) (S, []Effect[I])

type Session[I IIdentity] struct {
	// contains filtered or unexported fields
}