@kovojs/runtime

function handler<State = unknown, Params = Record<string, ElementParamValue>>(
  fn: ClientHandler<State, Params>,
): ClientHandler<State, Params>;

import { handler } from '@kovojs/runtime';

type CounterState = { count: number };

export const increment = handler<CounterState>((_event, ctx) => {
  ctx.state.count += 1;
});

function tempId(): string;

function trustedHtml(value: string | BrowserTrustedHTML): TrustedHtml;

function derive<const Inputs extends readonly string[], Value>(
  inputs: Inputs,
  fn: (...values: any[]) => Value,
): DeriveDefinition<Inputs, Value>;

import { derive } from '@kovojs/runtime';

export const total = derive(['price', 'quantity'], (price, quantity) =>
  Number(price) * Number(quantity),
);

type ElementParamValue = string | number | boolean;

interface HandlerContext<State = unknown, Params = Record<string, ElementParamValue>> {
  params: Params;
  signal: AbortSignal;
  state: State;
}

type ClientHandler<State = unknown, Params = Record<string, ElementParamValue>> = (
  event: Event,
  ctx: HandlerContext<State, Params>,
) => void | Promise<void>;

type ImportHandlerModule = (url: string) => Promise<Record<string, unknown>>;

interface MutationChangeRecord {
  domain: string;
  keys?: readonly string[];
}

interface OptimisticChange<Input = unknown> extends MutationChangeRecord {
  input: Input;
}

type OptimisticEntry<Input = unknown, Value = unknown> =
  | OptimisticTransform<Input, Value>
  | 'await-fragment';

type OptimisticFor<
  Definition extends Form<string, any, any>,
  QueryValues extends Record<string, unknown> = InvalidatedQueryValues<Definition>,
> = Omit<OptimisticPlan<FormInput<Definition>>, 'transforms'> & {
  transforms: {
    [QueryName in keyof QueryValues]: OptimisticEntry<
      FormInput<Definition>,
      QueryValues[QueryName]
    >;
  };
};

import { form } from '@kovojs/core';
import type { OptimisticFor } from '@kovojs/runtime';

const addToCart = form('cart/add');

export const addToCartOptimistic = {
  queue: 'cart',
  transforms: {},
} satisfies OptimisticFor<typeof addToCart>;

interface OptimisticPlan<Input = unknown> {
  keys?: Readonly<Record<string, OptimisticQueryKey<Input>>>;
  queue?: string;
  transforms: Record<string, OptimisticEntry<Input>>;
}

type OptimisticQueryKey<Input = unknown> =
  | ((change: OptimisticChange<Input>) => string | undefined)
  | string
  | undefined;

type OptimisticTransform<Input = unknown, Value = unknown> = (
  current: Value,
  input: Input,
) => Value;

interface BrowserTrustedHTML {
  readonly [Symbol.toStringTag]: 'TrustedHTML';
  toString(): string;
}

interface TrustedHtml {
  readonly __kovoTrustedHtml: true;
  readonly value: string | BrowserTrustedHTML;
}

interface DeriveDefinition<Inputs extends readonly string[], Value> {
  inputs: Inputs;
  run(...values: unknown[]): Value;
}

function applyDeferredStreamResponseToRuntime(
  options: ApplyDeferredStreamResponseToRuntimeOptions & { root: MorphRoot },
): AppliedDeferredStreamResponseWithRoot;
function applyDeferredStreamResponseToRuntime(
  options: ApplyDeferredStreamResponseToRuntimeOptions & { root?: undefined },
): AppliedMutationResponse & { chunks: AppliedMutationResponse[] };
function applyDeferredStreamResponseToRuntime(
  options: ApplyDeferredStreamResponseToRuntimeOptions,
): AppliedDeferredStreamResponseToRuntime;

function createEventBus<
  const Definitions extends readonly EventDefinition<string, JsonValue>[],
>(
  definitions: Definitions,
  options: EventBusOptions = {},
): TypedEventBus<EventPayloadMap<Definitions>>;

function abortRemovedIslandSignals(
  currentHtml: string,
  nextHtml: string,
  scope: IslandSignalScope = defaultIslandSignalScope,
): string[];

function readElementParams(element: EventElementLike): Record<string, ElementParamValue>;

function readElementState(element: EventElementLike): JsonValue;

function writeElementState(element: EventElementLike, state: JsonValue): void;

async function dispatchDelegatedEvent(
  event: DelegatedEvent,
  importModule: ImportHandlerModule,
  islandSignalScope: IslandSignalScope = defaultIslandSignalScope,
): Promise<void>;

function installKovoLoader(options: KovoLoaderOptions): KovoLoader;

function applyFragments(
  root: MorphRoot,
  fragments: readonly FragmentChunk[],
  morph: MorphFragment = replaceFragment,
  islandSignalScope: IslandSignalScope = defaultIslandSignalScope,
): string[];

const keyedDomMorph: MorphFragment = (target, html) => { /* … */ };

function morphDomElement(current: Element, next: Element): Element;

function morphStructuralTree(
  current: StructuralMorphNode,
  next: StructuralMorphNode,
): StructuralMorphNode;

function installMutationBroadcast(
  options: InstallMutationBroadcastOptions,
): MutationBroadcast;

function createMutationIdem(): string;

function isMutationBroadcastMessage(value: unknown): value is {
  body: string;
  changes: MutationChangeRecord[];
  type: 'kovo:mutation-response';
};

function readMutationChangeHeader(
  response: MutationResponseHeaderLike,
  onError?: RuntimeErrorReporter,
): MutationChangeRecord[];

function sanitizeMutationChangeRecord(value: unknown): MutationChangeRecord | null;

async function dispatchEnhancedFormSubmit(
  event: DelegatedEvent,
  options: EnhancedMutationLoaderOptions | undefined,
  islandSignalScope: IslandSignalScope = defaultIslandSignalScope,
  hooks: EnhancedFormSubmitHooks = {},
): Promise<boolean>;

function isEnhancedSubmitEvent(
  event: DelegatedEvent,
  options: EnhancedMutationLoaderOptions | undefined,
): boolean;

async function submitEnhancedMutation(
  options: EnhancedMutationSubmitOptions,
): Promise<EnhancedMutationAppliedResult>;

async function submitOptimisticEnhancedMutation<Input>(
  options: OptimisticEnhancedMutationSubmitOptions<Input>,
): Promise<
  AppliedMutationResponse & {
    appliedFragments: string[];
    changes: MutationChangeRecord[];
    idem: string;
    targets: string[];
  }
>;

function applyOptimisticTransforms<Input>(
  store: QueryStore,
  input: Input,
  plan: OptimisticPlan<Input>,
  change: OptimisticChange<Input> = optimisticChangeFromInput(input),
): PendingOptimism;

function installPagehideOptimismCleanup(
  options: PagehideOptimismCleanupOptions,
): () => void;

function now(): number;

function stampPendingQueries(
  root: PendingRoot,
  queryNames: readonly string[],
  pending: boolean,
): string[];

function createSubmitContext(options: SubmitContextOptions): SubmitContext;

function applyCompiledQueryUpdatePlan(
  root: QueryBindingRoot,
  queryName: string,
  value: unknown,
  plan: CompiledQueryUpdatePlan = {},
  options: ApplyCompiledQueryUpdatePlanOptions = {},
): AppliedCompiledQueryUpdatePlan;

function applyQueryBindings(
  root: QueryBindingRoot,
  queryName: string,
  value: unknown,
  options: ApplyQueryBindingsOptions = {},
): string[];

function applyStateBindings(
  root: QueryBindingRoot,
  state: unknown,
  options: ApplyStateBindingsOptions = {},
): Promise<string[]>;

function supportsQueryBindings(root: unknown): root is QueryBindingRoot;

function applyInlineQueryEventToRuntime(
  event: InlineQueryEvent,
  options: ApplyInlineQueryEventOptions,
): readonly string[];

function installInlineQueryEventHydration(
  options: InstallInlineQueryEventHydrationOptions,
): () => void;

async function refetchQueries(
  options: RefetchQueriesOptions,
): Promise<RefetchedQueryResponse[]>;

function createQueryStore(): QueryStore;

import { createQueryStore } from '@kovojs/runtime/client';

const store = createQueryStore();
store.set('cart', { count: 1 });

type AppliedDeferredStreamResponseToRuntime =
  | (AppliedMutationResponse & { chunks: AppliedMutationResponse[] })
  | AppliedDeferredStreamResponseWithRoot;

type AppliedDeferredStreamResponseWithRoot = AppliedMutationResponseWithRoot & {
  chunks: AppliedMutationResponseWithRoot[];
};

type ApplyDeferredStreamResponseToRuntimeOptions =
  ApplyDeferredStreamResponseToRuntimeBaseOptions & {
    root?: MorphRoot | undefined;
  };

interface DelegatedEvent {
  preventDefault?: () => void;
  submitter?: unknown;
  type: string;
  target: EventTargetLike | null;
}

interface EventBusOptions {
  onError?: (error: unknown, context: RuntimeErrorContext) => void;
  queryDataKeys?: readonly string[];
}

interface EventElementLike
  extends
    AttributeElementLike,
    ClosestElementLike<EventElementLike>,
    OptionalQuerySelectorAllRootLike<UploadProgressElementLike> {}

type EventListener<Payload> = (event: TypedEvent<string, Payload>) => void | Promise<void>;

type EventPayloadMap<Definitions extends readonly EventDefinition<string, JsonValue>[]> = {
  [Definition in Definitions[number] as Definition['name']]: Definition extends EventDefinition<
    string,
    infer Payload
  >
    ? Payload
    : never;
};

interface EventSubscription {
  off(): void;
}

interface EventTargetLike extends ClosestElementLike<EventElementLike> {}

interface RuntimeErrorContext {
  event?: DelegatedEvent | TypedEvent<string, unknown>;
  phase:
    | 'delegated-event'
    | 'event-listener'
    | 'execution-trigger'
    | 'enhanced-mutation'
    | 'mutation-broadcast'
    | 'query-hydration';
}

interface TypedEvent<Name extends string = string, Payload = unknown> {
  name: Name;
  payload: Payload;
}

interface TypedEventBus<EventMap extends Record<string, unknown>> {
  emit<Name extends Extract<keyof EventMap, string>>(name: Name, payload: EventMap[Name]): void;
  events: readonly Extract<keyof EventMap, string>[];
  on<Name extends Extract<keyof EventMap, string>>(
    name: Name,
    listener: EventListener<EventMap[Name]>,
  ): EventSubscription;
}

interface UploadProgressElementLike extends AttributeWriterLike {
  setAttribute(name: string, value: string): void;
}

type IslandSignalScope = object;

interface LoaderLifecycleTarget extends ListenerTargetLike<DelegatedEvent> {}

interface LoaderRoot
  extends
    LoaderLifecycleTarget,
    OptionalQuerySelectorAllRootLike<EventElementLike | QueryScriptLike>,
    VisibilityStateLike {}

interface VisibleObserver {
  observe(element: EventElementLike): void;
  unobserve(element: EventElementLike): void;
}

interface VisibleObserverEntry {
  isIntersecting: boolean;
  target: EventElementLike;
}

type VisibleObserverFactory = (
  callback: (entries: readonly VisibleObserverEntry[]) => void,
) => VisibleObserver;

interface KovoLoader {
  dispose(): void;
  events: readonly string[];
}

interface KovoLoaderOptions {
  discardPendingOptimism?: () => readonly string[] | void;
  enhancedMutations?: EnhancedMutationLoaderOptions;
  events?: readonly string[];
  focusTarget?: LoaderLifecycleTarget;
  importModule: ImportHandlerModule;
  onError?: (error: unknown, context: RuntimeErrorContext) => void;
  applyQuery?: QueryApplyInterposition;
  queryEventTarget?: QueryEventHydrationTarget;
  queryPlans?: CompiledQueryUpdatePlans;
  queryRefetch?: QueryRefetchOptions;
  requestIdle?: (callback: () => void) => void;
  visibleObserver?: VisibleObserverFactory;
  queryStore?: QueryStore;
  refetchOnFocus?: (queries: readonly string[]) => void | Promise<void>;
  refetchOnFocusOptOut?: readonly string[];
  root: LoaderRoot;
}

class DomMorphRoot implements MorphRoot {
  private readonly root: FragmentTargetRoot;

  constructor(root: FragmentTargetRoot) {
    this.root = root;
  }

  findFragmentTarget(target: string): MorphTarget | null {
    const element = findFragmentTargetElement(this.root, target);

    return element ? new DomMorphTarget(element) : null;
  }
}

class DomMorphTarget implements MorphTarget {
  element: Element;

  constructor(element: Element) {
    this.element = element;
  }

  readHtml(): string {
    return this.element.innerHTML;
  }

  appendHtml(html: string): void {
    const template = document.createElement('template');
    template.innerHTML = html.trim();
    this.element.append(...Array.from(template.content.childNodes));
  }

  replaceWithHtml(html: string): void {
    const template = document.createElement('template');
    template.innerHTML = html.trim();
    const next = firstMorphElement(template.content);
    const activeState = captureActiveDomState(this.element);
    const scrollStates = captureDomScrollStates(this.element);

    if (!next) {
      this.element.replaceChildren();
      return;
    }

    morphDomElement(this.element, next);
    restoreActiveDomState(activeState);
    restoreDomScrollStates(scrollStates);
  }
}

type MorphFragment = (target: MorphTarget, html: string) => void;

interface MorphRoot {
  findFragmentTarget(target: string): MorphTarget | null;
}

interface MorphTarget {
  appendHtml?(html: string): void;
  readHtml?(): string;
  replaceWithHtml(html: string): void;
}

interface StructuralMorphBrowserState {
  focused?: boolean;
  islandState?: unknown;
  scroll?: { left: number; top: number };
  selection?: { direction?: 'backward' | 'forward' | 'none'; end: number; start: number };
}

type StructuralMorphKey = string | number;

interface StructuralMorphNode {
  browserState?: StructuralMorphBrowserState;
  children?: StructuralMorphNode[];
  key?: StructuralMorphKey | null;
  props?: Record<string, unknown>;
  text?: string;
  type: string;
}

interface BroadcastLike {
  close?: () => void;
  onmessage: ((event: { data: unknown }) => void) | null;
  postMessage(message: unknown): void;
}

interface InstallMutationBroadcastOptions {
  applyQuery?: QueryApplyInterposition;
  channel: BroadcastLike;
  morph?: MorphFragment;
  onError?: RuntimeErrorReporter;
  onChanges?: (changes: readonly MutationChangeRecord[]) => void;
  onAppliedQueries?: (queries: readonly string[]) => void;
  queryPlans?: CompiledQueryUpdatePlans;
  root?: MorphRoot;
  store: QueryStore;
}

interface MutationBroadcast {
  close(): void;
  publish(body: string, changes?: readonly MutationChangeRecord[]): void;
}

type EnhancedMutationAppliedResult = AppliedMutationResponse & {
  appliedFragments: string[];
  changes: MutationChangeRecord[];
  idem: string;
  targets: string[];
};

class MutationQueue {
  #tails = new Map<string, Promise<unknown>>();

  run<Value>(queue: string | undefined, task: MutationTask<Value>): Promise<Value> {
    if (!queue) return Promise.resolve().then(task);

    const previous = this.#tails.get(queue) ?? Promise.resolve();
    const run = previous.then(task, task);
    const tail = run
      .catch(() => undefined)
      .finally(() => {
        if (this.#tails.get(queue) === tail) {
          this.#tails.delete(queue);
        }
      });

    this.#tails.set(queue, tail);
    return run;
  }

  pending(queue: string): boolean {
    return this.#tails.has(queue);
  }
}

type MutationTask<Value> = () => Promise<Value> | Value;

interface MutationResponseHeaderLike {
  headers?: {
    get(name: string): string | null;
  };
}

interface TargetCollectorRoot extends QuerySelectorAllRootLike<TargetElementLike> {}

interface EnhancedFormElementLike extends EventElementLike {
  action: string;
  id?: string | undefined;
  method?: string | undefined;
  submit?: () => void;
}

interface EnhancedFormLike {
  action: string;
  getAttribute?(name: string): string | null;
  id?: string | { toString(): string } | undefined;
  method?: string | undefined;
}

type EnhancedMutationFetch = (
  url: string,
  options: EnhancedMutationFetchOptions,
) => Promise<EnhancedMutationResponseLike>;

interface EnhancedMutationFetchOptions {
  body: unknown;
  headers: Record<string, string>;
  keepalive: boolean;
  method: string;
  onUploadProgress?: (progress: UploadProgress) => void;
}

interface EnhancedMutationLoaderOptions {
  applyQuery?: QueryApplyInterposition;
  broadcast?: MutationBroadcast;
  fetch: EnhancedMutationFetch;
  formData?: (form: EnhancedFormElementLike, event: DelegatedEvent) => unknown;
  idem?: () => string;
  morph?: MorphFragment;
  /**
   * Handles enhanced form submit failures after preventDefault. When present,
   * the form layer owns the error and native submit fallback is skipped.
   *
   * SPEC.md section 9.2 keeps enhanced and no-JS form paths equivalent; this
   * hook is the enhanced path's reporting seam for failed fragment submissions.
   */
  onError?: (error: unknown, form: EnhancedFormElementLike) => void;
  onUploadProgress?: (progress: UploadProgress, form: EnhancedFormElementLike) => void;
  pendingRoot?: PendingRoot;
  queryPlans?: CompiledQueryUpdatePlans;
  root: MorphRoot & TargetCollectorRoot;
  store: QueryStore;
}

interface EnhancedMutationResponseLike {
  headers?: {
    get(name: string): string | null;
  };
  ok?: boolean;
  status?: number;
  text(): Promise<string>;
}

interface EnhancedMutationSubmitOptions {
  applyQuery?: QueryApplyInterposition;
  broadcast?: MutationBroadcast;
  /**
   * The page-level build token (SPEC §9.1.1). Defaults to `readPageBuildToken()`
   * (`<meta name="kovo-build">`) when omitted; deltas apply only when it matches
   * the response's `Kovo-Build` token.
   */
  expectedBuildToken?: string;
  fetch: EnhancedMutationFetch;
  form: EnhancedFormLike;
  formData: unknown;
  idem?: string;
  islandSignalScope?: IslandSignalScope;
  morph?: MorphFragment;
  /**
   * Refetch-full handler for delta chunks with a missing/stale base (SPEC §9.1.1).
   * Defaults to a `/_q/<wireKey>` refetcher over the submit `fetch` when omitted.
   */
  onDeltaMiss?: OnDeltaMiss;
  /**
   * Reports mutation submit/apply failures. Direct submit callers still receive
   * the thrown error; dispatchEnhancedFormSubmit decides whether a form-layer
   * error has been handled.
   */
  onError?: (error: unknown) => void;
  onUploadProgress?: (progress: UploadProgress) => void;
  pendingQueries?: readonly string[];
  pendingRoot?: PendingRoot;
  queryPlans?: CompiledQueryUpdatePlans;
  root: MorphRoot & TargetCollectorRoot;
  store: QueryStore;
}

interface UploadProgress {
  loaded: number;
  total?: number;
}

interface OptimisticEnhancedMutationSubmitOptions<
  Input,
> extends EnhancedMutationSubmitOptions {
  change?: OptimisticChange<Input>;
  input: Input;
  optimistic: OptimisticPlan<Input>;
  queue?: MutationQueue;
  rebaser: OptimisticRebaser;
}

class OptimisticRebaser {
  #pendingByQuery = new Map<string, PendingTransform[]>();
  #serverTruthByQuery = new Map<string, unknown>();
  #store: QueryStore;

  constructor(store: QueryStore) {
    this.#store = store;
  }

  add<Input>(id: string, input: Input, plan: OptimisticPlan<Input>): void {
    this.addChange(id, optimisticChangeFromInput(input), plan);
  }

  addChange<Input>(id: string, change: OptimisticChange<Input>, plan: OptimisticPlan<Input>): void {
    for (const [queryName, transform] of Object.entries(plan.transforms)) {
      if (transform === 'await-fragment') continue;

      const key = optimisticQueryKey(plan, queryName, change);
      const storeKey = queryStoreKey(queryName, key);
      const pending = this.#pendingByQuery.get(storeKey) ?? [];
      if (pending.length === 0) {
        this.#serverTruthByQuery.set(storeKey, structuredClone(this.#store.get(queryName, key)));
      }
      pending.push({ change, id, transform: transform as OptimisticTransform });
      this.#pendingByQuery.set(storeKey, pending);

      this.#store.set(queryName, transform(this.#store.get(queryName, key), change.input), key);
    }
  }

  settle(id: string): void {
    for (const [queryName, pending] of this.#pendingByQuery) {
      const next = pending.filter((item) => item.id !== id);
      if (next.length === 0) {
        this.#pendingByQuery.delete(queryName);
        this.#serverTruthByQuery.delete(queryName);
      } else {
        this.#pendingByQuery.set(queryName, next);
      }
    }
// … truncated (71 more lines); see the package source for the full declaration.

interface PagehideOptimismCleanupOptions {
  discardPendingOptimism: () => readonly string[] | void;
  root: PagehideRoot;
}

interface PendingOptimism {
  commit(): void;
  restore(): void;
  snapshot: QuerySnapshot;
}

interface PendingTransform<Input = unknown> {
  change: OptimisticChange<Input>;
  id: string;
  transform: OptimisticTransform<Input>;
}

interface PendingElementLike extends AttributeMutatorLike {}

interface PendingRoot extends QuerySelectorAllRootLike<PendingElementLike> {}

interface SubmitContext {
  submit<Definition extends SubmitFormDefinition>(
    form: Definition,
    options: SubmitOptions<FormInput<Definition>, FormFailure<Definition>>,
  ): Promise<
    AppliedMutationResponse & { appliedFragments: string[]; idem: string; targets: string[] }
  >;
}

interface SubmitContextOptions {
  actionFor?: (form: SubmitFormDefinition) => string;
  broadcast?: MutationBroadcast;
  fetch: EnhancedMutationFetch;
  method?: string;
  morph?: MorphFragment;
  queryPlans?: CompiledQueryUpdatePlans;
  root: MorphRoot & TargetCollectorRoot;
  store: QueryStore;
}

type SubmitFormDefinition = Form<string, any, any>;

interface SubmitOptions<Input extends Record<string, JsonValue>, Failure> {
  action?: string;
  idem?: string;
  input: Input;
  method?: string;
  onError?: (failure: Failure) => void | Promise<void>;
  parseError?: (body: string) => Failure;
}

interface AppliedCompiledQueryUpdatePlan {
  bindings: string[];
  derives: string[];
  stamps: string[];
  templateStamps: string[];
}

interface ApplyStateBindingsOptions extends ApplyQueryBindingsOptions {
  importModule?: (url: string) => Promise<Record<string, unknown>>;
}

interface CompiledQueryDerive {
  name: string;
  select(value: unknown, root: QueryBindingRoot): unknown;
  selector?: string;
}

interface CompiledQueryStamp {
  attr: string;
  select(value: unknown, root: QueryBindingRoot): unknown;
  selector: string;
}

interface CompiledQueryTemplateStamp {
  key: string | ((item: unknown, index: number) => string | number);
  list: string;
  render(item: unknown, index: number): string;
  selector: string;
}

interface CompiledQueryUpdatePlan {
  bindings?: boolean;
  derives?: readonly CompiledQueryDerive[];
  stamps?: readonly CompiledQueryStamp[];
  templateStamps?: readonly CompiledQueryTemplateStamp[];
}

type CompiledQueryUpdatePlans = Readonly<
  Record<string, CompiledQueryUpdatePlan | undefined>
>;

interface QueryBindingElement
  extends AttributeElementLike, ClosestElementLike<QueryBindingElement> {
  checked?: boolean;
  indeterminate?: boolean;
  scrollLeft?: number;
  scrollTop?: number;
  tagName?: string;
  textContent?: string | null;
  value?: string;
}

interface QueryBindingRoot extends QuerySelectorAllRootLike<QueryBindingElement> {}

interface TemplateStampHost extends QueryBindingElement {
  reconcileTemplateStamp(items: readonly TemplateStampItem[]): void;
}

interface TemplateStampItem {
  html: string;
  index: number;
  key: string;
  value: unknown;
}

interface ApplyInlineQueryEventOptions {
  applyQuery?: QueryApplyInterposition;
  onError?: RuntimeErrorReporter;
  queryPlans?: CompiledQueryUpdatePlans;
  root?: unknown;
  store: QueryStore;
}

interface InlineQueryEvent {
  detail?: InlineQueryEventDetail;
}

interface InlineQueryEventDetail {
  queries: QueryElementChunkLike[];
}

interface InstallInlineQueryEventHydrationOptions extends ApplyInlineQueryEventOptions {
  onAppliedQueries?: (queries: readonly string[]) => void;
  target: QueryEventHydrationTarget;
}

interface QueryEventHydrationTarget extends ListenerTargetLike<InlineQueryEvent> {}

interface QueryRefetchFetch {
  (
    url: string,
    init: {
      cache: 'no-store';
      headers: Record<string, string>;
      method: 'GET';
    },
  ): Promise<QueryRefetchResponse> | QueryRefetchResponse;
}

interface QueryRefetchOptions {
  fetch: QueryRefetchFetch;
  /**
   * Reports typed-read fetch, response-body, and wire-apply failures. Refetch is
   * a visible-return background layer, so individual query failures are reported
   * and skipped while later queries continue under SPEC.md §4.4 hydration.
   */
  onError?: (error: unknown) => void;
  urlForQuery?: (query: string) => string | undefined;
}

interface QueryRefetchResponse {
  ok?: boolean;
  status?: number;
  text(): Promise<string> | string;
}

interface RefetchQueriesOptions extends QueryRefetchOptions {
  applyQuery?: QueryApplyInterposition;
  queryPlans?: CompiledQueryUpdatePlans;
  queries: readonly string[];
  queryStore: QueryStore;
  root?: unknown;
}

interface RefetchedQueryResponse {
  fragments: [];
  queries: readonly string[];
}

type QuerySnapshot = Map<string, unknown>;

interface QueryStore {
  get<Value = unknown>(name: string, key?: string): Value | undefined;
  snapshot(
    names: readonly string[],
    keys?: Readonly<Record<string, string | undefined>>,
  ): QuerySnapshot;
  set<Value = unknown>(name: string, value: Value, key?: string): void;
  subscribe<Value = unknown>(name: string, plan: QueryUpdatePlan<Value>, key?: string): () => void;
}

type QueryUpdatePlan<Value = unknown> = (value: Value) => void;