Runtime

/** Configuration for crash handling, with custom crash UI and/or crash reporting. */
type CrashConfig = Readonly<{
  report: (context: CrashContext<Model, Message>) => void
  view: (context: CrashContext<Model, Message>) => Document
}>

/**
 * Context provided to crash.view and crash.report when the runtime encounters
 *  an unrecoverable error. `message` is the Message being processed when the
 *  crash occurred, present as an `Option` because a crash during the initial
 *  render has no triggering Message.
 */
type CrashContext = Readonly<{
  error: Error
  message: Option.Option<Message>
  model: Model
}>

/**
 * DevTools configuration.
 * 
 * Pass `false` to disable DevTools entirely.
 * 
 * - `show`: `'Development'` (default) enables in dev mode only, `'Always'` enables in all environments including production.
 * - `position`: Where the badge and panel appear. Defaults to `'BottomRight'`.
 * - `mode`: `'TimeTravel'` (default) enables full time-travel debugging. `'Inspect'` allows browsing state snapshots without pausing the app. Pass `{ development, production }` to use different modes per environment. Useful when DevTools is shown in production (`show: 'Always'`) and you want `'TimeTravel'` only in local development.
 * - `banner`: Optional text shown as a banner at the top of the panel.
 * - `excludeFromHistory`: Message `_tag` values whose dispatches should not be recorded in DevTools history. The Messages still drive `update` and the runtime as usual; they just don't appear in the history panel and don't pay the per-Message diff cost. Use for high-frequency Messages (animation frames, pointer moves, scroll events) that would flood history without adding insight.
 * - `maxEntries`: Maximum number of recorded Messages retained in history before the oldest is evicted. Defaults to 100. Clamped to the range 20-500: smaller values keep the panel snappy under high message rates, larger values give you more scroll-back. Each retained entry stores a full Model snapshot, so memory cost scales linearly with both `maxEntries` and your Model size.
 */
type DevToolsConfig = false | Readonly<{
  banner: string
  excludeFromHistory: ReadonlyArray<string>
  maxEntries: number
  Message: Schema.Codec<any, any, unknown, unknown>
  mode: DevToolsModeConfig
  position: DevToolsPosition
  show: Visibility
}>

/**
 * Controls DevTools interaction mode.
 * 
 * - `'Inspect'`: Messages stream in and clicking a row shows its state snapshot without pausing the app.
 * - `'TimeTravel'`: Clicking a row pauses the app at that historical state. Resume to continue.
 */
type DevToolsMode = "Inspect" | "TimeTravel"

/**
 * Mode value for the DevTools panel. Either a single mode used in every
 *  environment, or an object selecting different modes for development and
 *  production. Use the object form to keep `'TimeTravel'` for local debugging
 *  while shipping the safer `'Inspect'` mode to users. `'TimeTravel'` in
 *  production pauses the user's app when a history row is clicked.
 */
type DevToolsModeConfig = DevToolsMode | Readonly<{
  development: DevToolsMode
  production: DevToolsMode
}>

/** A configured Foldkit runtime returned by `makeProgram`, passed to `run` to start the application. */
type MakeRuntimeReturn = Readonly<{
  runtimeId: string
  start: (hmrModel?: unknown) => Effect.Effect<void>
}>

/** Configuration for `makeProgram` without flags or URL routing. */
type ProgramConfig = BaseProgramConfig<Model, Message, Resources, ManagedResourceServices> & Readonly<{
  init: () => readonly [Model, ReadonlyArray<Command<Message, never, Resources | ManagedResourceServices>>]
}>

/** Configuration for `makeProgram` with flags but no URL routing. */
type ProgramConfigWithFlags = BaseProgramConfig<Model, Message, Resources, ManagedResourceServices> & Readonly<{
  flags: Effect.Effect<Flags>
  Flags: Schema.Codec<Flags, any, unknown, unknown>
  init: (flags: Flags) => readonly [Model, ReadonlyArray<Command<Message, never, Resources | ManagedResourceServices>>]
}>

/** The `init` function type for programs without URL routing. */
type ProgramInit = Flags extends void
  ? () => readonly [Model, ReadonlyArray<Command<Message, never, Resources | ManagedResourceServices>>]
  : (flags: Flags) => readonly [Model, ReadonlyArray<Command<Message, never, Resources | ManagedResourceServices>>]

/** Configuration for URL routing with handlers for URL requests and URL changes. */
type RoutingConfig = Readonly<{
  onUrlChange: (url: Url) => Message
  onUrlRequest: (request: UrlRequest) => Message
}>

/** Configuration for `makeProgram` with URL routing but no flags. */
type RoutingProgramConfig = BaseProgramConfig<Model, Message, Resources, ManagedResourceServices> & Readonly<{
  init: (url: Url) => readonly [Model, ReadonlyArray<Command<Message, never, Resources | ManagedResourceServices>>]
  routing: RoutingConfig<Message>
}>

/** Configuration for `makeProgram` with flags and URL routing. */
type RoutingProgramConfigWithFlags = BaseProgramConfig<Model, Message, Resources, ManagedResourceServices> & Readonly<{
  flags: Effect.Effect<Flags>
  Flags: Schema.Codec<Flags, any, unknown, unknown>
  init: (flags: Flags, url: Url) => readonly [Model, ReadonlyArray<Command<Message, never, Resources | ManagedResourceServices>>]
  routing: RoutingConfig<Message>
}>

/** The `init` function type for programs with URL routing, receives the current URL and optional flags. */
type RoutingProgramInit = Flags extends void
  ? (url: Url) => readonly [Model, ReadonlyArray<Command<Message, never, Resources | ManagedResourceServices>>]
  : (flags: Flags, url: Url) => readonly [Model, ReadonlyArray<Command<Message, never, Resources | ManagedResourceServices>>]

/**
 * Slow view warning configuration.
 * 
 * Pass `false` to disable warnings entirely.
 * 
 * - `show`: `'Development'` (default) enables in dev mode only, `'Always'` enables in all environments.
 * - `thresholdMs`: Duration in ms above which a view is considered slow. Defaults to 16 (one frame at 60fps).
 * - `onSlowView`: Custom callback invoked when a slow view is detected. Defaults to `console.warn`.
 */
type SlowViewConfig = false | Readonly<{
  onSlowView: (context: SlowViewContext<Model, Message>) => void
  show: Visibility
  thresholdMs: number
}>

/** Context provided to the slow view callback when a view exceeds the time budget. */
type SlowViewContext = Readonly<{
  durationMs: number
  message: Option.Option<Message>
  model: Model
  thresholdMs: number
}>

/** Controls when a feature is shown. */
type Visibility = "Development" | "Always"