beam

type Beam[T any] interface {
	// Effect returns the current value and rerenders the closest dynamic parent
	// when the value changes.
	Effect(ctx context.Context) (T, bool)

	// Sub subscribes to the value stream. onValue is called immediately with the
	// current value in the same goroutine, and again on every update.
	// Only instance runtime context is allowed.
	//
	// The subscription continues until:
	//   - onValue returns true, or
	//   - a dynamic parent is unmounted.
	//
	// It returns false if the context was already canceled or does not belong to
	// an instance runtime.
	Sub(ctx context.Context, onValue func(context.Context, T) bool) bool

	// ReadAndSub returns the current value and then subscribes to future
	// updates. onValue is called only for subsequent updates.
	// Only instance runtime context is allowed.
	//
	// It returns false if the context was canceled or does not belong to an
	// instance runtime.
	ReadAndSub(ctx context.Context, onValue func(context.Context, T) bool) (T, bool)

	// Read returns the current value without creating a subscription.
	// Only instance runtime context is allowed.
	//
	// It returns false if the context was canceled or does not belong to an
	// instance runtime.
	Read(ctx context.Context) (T, bool)

	// AddWatcher attaches a low-level watcher for separate init, update, and
	// cancellation callbacks. Only instance runtime context is allowed.
	AddWatcher(ctx context.Context, w Watcher[T]) (context.CancelFunc, bool)
	// contains filtered or unexported methods
}

type Cinema = *cinema

type Core interface {
	Cinema() Cinema
}

type Door interface {
	ReadFrame() shredder.Frame
	Context() context.Context
}

type Source[T any] interface {
	Beam[T]

	// Update sets a new value and propagates it to subscribers and derived
	// beams. The update is applied only if it passes the source's distinct
	// function. Any context is allowed.
	Update(context.Context, T)

	// XUpdate behaves like [Source.Update] and returns a channel that reports
	// when propagation has finished.
	//
	// The channel receives nil on successful propagation or an error if the
	// context is invalid or the instance ends before propagation finishes. Do
	// not wait on it during rendering. If you need to wait, do it in a hook,
	// inside `doors.Go(...)`, or in your own goroutine with `doors.Free(ctx)`.
	XUpdate(context.Context, T) <-chan error

	// Mutate computes the next value from the current value and propagates it
	// if it passes the source's distinct function. The function receives a copy
	// of the current value and must return the next value. Returning an
	// unchanged copy is a no-op when a distinct function is in use.
	// Any context is allowed.
	Mutate(context.Context, func(T) T)

	// XMutate behaves like [Source.Mutate] and returns a channel that reports
	// when propagation has finished.
	//
	// The channel receives nil on successful propagation or an error if the
	// context is invalid or the instance ends before propagation finishes. Do
	// not wait on it during rendering. If you need to wait, do it in a hook,
	// inside `doors.Go(...)`, or in your own goroutine with `doors.Free(ctx)`.
	XMutate(context.Context, func(T) T) <-chan error

	// Get returns the most recently stored value without requiring a runtime
	// context.
	//
	// Unlike [Beam.Read], Get does not participate in render-cycle consistency
	// guarantees. Use Read when consistency across the component tree matters.
	Get() T

	// DisableSkipping forces every committed value to propagate, even if newer
	// values arrive before earlier updates finish syncing. This is useful when a
	// source is used as a communication channel and every message matters.
	DisableSkipping()
}

type Watcher[T any] interface {
	// Cancel is called when the watcher stops because of context cancellation or
	// an explicit cancel call.
	Cancel()
	// Watch receives the initial value synchronously and later updates
	// asynchronously. Returning true stops the watcher.
	Watch(ctx context.Context, value T) bool
}