gospa

type App struct {
	// Config is the application configuration.
	Config Config
	// Router is the file-based router.
	Router *routing.Router
	// Fiber is the underlying Fiber app.
	Fiber *fiberpkg.App
	// Hub is the WebSocket hub for real-time updates.
	Hub *fiber.WSHub
	// StateMap is the global state map.
	StateMap *state.StateMap
	// contains filtered or unexported fields
}

type Config struct {
	// RoutesDir is the directory containing route files.
	RoutesDir string
	// RoutesFS is the filesystem containing route files (optional). Takes precedence over RoutesDir if provided.
	RoutesFS fs.FS
	// DevMode enables development features.
	DevMode bool
	// RuntimeScript is the path to the client runtime script.
	RuntimeScript string
	// StaticDir is the directory for static files.
	StaticDir string
	// StaticPrefix is the URL prefix for static files.
	StaticPrefix string
	// AppName is the application name.
	AppName string
	// DefaultState is the initial state for new sessions.
	DefaultState map[string]interface{}
	// EnableWebSocket enables WebSocket support.
	EnableWebSocket bool
	// WebSocketPath is the WebSocket endpoint path.
	WebSocketPath string
	// WebSocketMiddleware allows injecting session/auth middleware before WebSocket upgrade.
	WebSocketMiddleware fiberpkg.Handler
	// Logger is the structured logger. Defaults to slog.Default().
	Logger *slog.Logger

	// Performance Options
	// CompressState enables gzip compression of outbound WebSocket state payloads.
	CompressState bool
	// StateDiffing enables delta-only "patch" WebSocket messages for state syncs.
	StateDiffing   bool
	CacheTemplates bool // Cache compiled templates (SSG only)
	// RuntimeTier specifies the complexity of the client runtime.
	RuntimeTier compiler.RuntimeTier
	// SimpleRuntimeSVGs allows SVG elements in the simple runtime sanitizer.
	SimpleRuntimeSVGs bool
	// DisableSanitization disables client-side HTML sanitization for SPA navigation.
	DisableSanitization bool
	// NotificationBufferSize sets the size of the state change notification queue (default 1024).
	NotificationBufferSize int

	// WebSocket Options — these values are passed directly to the client runtime's init() call.
	WSReconnectDelay time.Duration // Initial reconnect delay (default 1s)
	WSMaxReconnect   int           // Max reconnect attempts (default 10)
	WSHeartbeat      time.Duration // Heartbeat ping interval (default 30s)

	// WSMaxMessageSize limits the maximum payload size for WebSocket messages (default 64KB).
	WSMaxMessageSize int
	// WSConnRateLimit sets the refilling rate in connections per second for WebSocket upgrades (default 1.5).
	WSConnRateLimit float64
	// WSConnBurst sets the burst capacity for WebSocket connection upgrades (default 15.0).
	WSConnBurst float64

	// Hydration Options
	HydrationMode    string
	HydrationTimeout int // ms before force hydrate

	// Serialization Options
	SerializationFormat string
	StateSerializer     StateSerializerFunc
	StateDeserializer   StateDeserializerFunc

	// Routing Options
	DisableSPA bool // Disable SPA navigation completely

	// Rendering Strategy Defaults
	DefaultRenderStrategy  routing.RenderStrategy
	DefaultRevalidateAfter time.Duration

	// Remote Action Options
	MaxRequestBodySize                int              // Maximum allowed size for remote action request bodies
	RemotePrefix                      string           // Prefix for remote action endpoints (default "/_gospa/remote")
	RemoteActionMiddleware            fiberpkg.Handler // Optional middleware
	AllowUnauthenticatedRemoteActions bool             // Default false

	// Security Options
	AllowedOrigins        []string
	EnableCSRF            bool
	ContentSecurityPolicy string
	PublicOrigin          string
	// StrictProduction enforces hard startup validation for production deployments.
	StrictProduction bool
	// AllowInsecureWS allows unsecure ws:// connections even on https:// pages.
	// This is useful for development setups with reverse proxies that don't support wss://.
	AllowInsecureWS bool
	// AllowPortsWithInsecureWS allows unsecure ws:// connections for these specific ports, even on https:// pages.
	// This is useful for development setups with reverse proxies that don't support wss://.
	// Defaults to []int{3000}.
	AllowPortsWithInsecureWS []int
	SSGCacheMaxEntries       int           // Default: 500
	SSGCacheTTL              time.Duration // Default: 0 (no expiry)

	// Prefork enables Fiber's prefork mode.
	Prefork bool

	// Storage defines the external storage backend for sessions and state.
	Storage store.Storage

	// PubSub defines the messaging backend for multi-process broadcasting.
	PubSub store.PubSub

	// NavigationOptions configures optional client-side navigation behavior.
	NavigationOptions NavigationOptions

	// ISR Options
	// ISRSemaphoreLimit limits concurrent ISR background revalidations.
	ISRSemaphoreLimit int
	// ISRTimeout sets the maximum time for a background ISR revalidation.
	ISRTimeout time.Duration

	// IslandsBundlePath is the path to the islands bundle script.
	IslandsBundlePath string
	// PreloadCSS contains paths to CSS files that should be preloaded with high priority.
	PreloadCSS []string

	// BuildManifest is the loaded manifest.json (optional).
	BuildManifest map[string]string
	// ManifestPath is the path to manifest.json (default: "./manifest.json").
	ManifestPath string
}

type ConfigOption func(*Config)

type NavigationIdleCallbackBatchUpdatesConfig struct {
	Enabled             *bool `json:"enabled,omitempty"`
	FallbackToMicrotask *bool `json:"fallbackToMicrotask,omitempty"`
}

type NavigationLazyRuntimeInitializationConfig struct {
	Enabled       *bool `json:"enabled,omitempty"`
	DeferBindings *bool `json:"deferBindings,omitempty"`
}

type NavigationOptions struct {
	SpeculativePrefetching         *NavigationSpeculativePrefetchingConfig    `json:"speculativePrefetching,omitempty"`
	URLParsingCache                *NavigationURLParsingCacheConfig           `json:"urlParsingCache,omitempty"`
	IdleCallbackBatchUpdates       *NavigationIdleCallbackBatchUpdatesConfig  `json:"idleCallbackBatchUpdates,omitempty"`
	LazyRuntimeInitialization      *NavigationLazyRuntimeInitializationConfig `json:"lazyRuntimeInitialization,omitempty"`
	ServiceWorkerNavigationCaching *NavigationServiceWorkerCachingConfig      `json:"serviceWorkerNavigationCaching,omitempty"`
	ViewTransitions                *NavigationViewTransitionsConfig           `json:"viewTransitions,omitempty"`
	ProgressBar                    *NavigationProgressBarConfig               `json:"progressBar,omitempty"`
}

type NavigationProgressBarConfig struct {
	Enabled *bool   `json:"enabled,omitempty"`
	Color   *string `json:"color,omitempty"`
	Height  *string `json:"height,omitempty"`
	Delay   *int    `json:"delay,omitempty"`
}

type NavigationServiceWorkerCachingConfig struct {
	Enabled   *bool  `json:"enabled,omitempty"`
	CacheName string `json:"cacheName,omitempty"`
	Path      string `json:"path,omitempty"`
}

type NavigationSpeculativePrefetchingConfig struct {
	Enabled        *bool `json:"enabled,omitempty"`
	TTL            *int  `json:"ttl,omitempty"`
	HoverDelay     *int  `json:"hoverDelay,omitempty"`
	ViewportMargin *int  `json:"viewportMargin,omitempty"`
}

type NavigationURLParsingCacheConfig struct {
	Enabled *bool `json:"enabled,omitempty"`
	MaxSize *int  `json:"maxSize,omitempty"`
	TTL     *int  `json:"ttl,omitempty"`
}

type NavigationViewTransitionsConfig struct {
	Enabled           *bool `json:"enabled,omitempty"`
	FallbackToClassic *bool `json:"fallbackToClassic,omitempty"`
}

type StateDeserializerFunc func([]byte, interface{}) error

type StateSerializerFunc func(interface{}) ([]byte, error)