beam

type Beam[T any] interface {
	// 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

	// XSub behaves like [Beam.Sub] and also:
	//   - accepts onCancel, called when the subscription ends because of
	//     cancellation, and
	//   - returns a cancel function for manual termination.
	XSub(ctx context.Context, onValue func(context.Context, T) bool, onCancel func()) (context.CancelFunc, 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)

	// XReadAndSub behaves like [Beam.ReadAndSub] and also returns a cancel
	// function plus an optional onCancel callback.
	// If ok is false, the returned value is undefined and no subscription was
	// established.
	XReadAndSub(ctx context.Context, onValue func(context.Context, T) bool, onCancel func()) (T, context.CancelFunc, 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 {
	NewFrame() 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
}