@kontsedal/olas-core 0.0.1-rc.0

package/dist/types-CAMgqCMz.d.mts

@@ -0,0 +1,816 @@
+//#region src/emitter.d.ts
+/**
+ * Synchronous fan-out event bus. Handlers run in the order they subscribed.
+ * Handlers added during emit don't fire for the current emission; handlers
+ * removed during emit are skipped from that point in the iteration.
+ *
+ * `Emitter<void>` exposes `emit()` (no argument); other shapes expose
+ * `emit(value: T)`.
+ *
+ * Spec §7, §20.6.
+ */
+type Emitter<T> = {
+  emit: [T] extends [void] ? () => void : (value: T) => void; /** Subscribe to every emission. Returns the unsubscribe function. */
+  on(handler: (value: T) => void): () => void; /** Subscribe to the next emission only. Auto-unsubscribes after firing. */
+  once(handler: (value: T) => void): () => void; /** Tear down the emitter. Subsequent `emit` / `on` / `once` are no-ops. */
+  dispose(): void;
+};
+/**
+ * Create a standalone emitter. Handlers persist until explicitly unsubscribed
+ * (or the emitter is disposed). Use this for emitters that live outside any
+ * single controller — typically in deps. Use `ctx.emitter()` for emitters that
+ * should auto-clean with a controller.
+ */
+declare function createEmitter<T = void>(): Emitter<T>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Context passed to a root's `onError` handler. `kind` identifies where in
+ * the controller's surface the throw originated; `controllerPath` is the
+ * path from root to the controller that owned the failing code; `queryKey`
+ * is set for `cache` kinds. Spec §12, §20.9.
+ *
+ * `'plugin'` is used for exceptions raised by `QueryClientPlugin` callbacks
+ * (`@kontsedal/olas-cross-tab` and friends); SPEC §13.2.
+ */
+type ErrorContext = {
+  kind: 'effect' | 'cache' | 'mutation' | 'emitter' | 'construction' | 'plugin';
+  controllerPath: readonly string[];
+  queryKey?: readonly unknown[];
+};
+//#endregion
+//#region src/signals/types.d.ts
+/**
+ * Read-only reactive value. Reading `.value` inside a tracking scope
+ * (`computed` / `effect`) registers a dependency; `peek()` reads without
+ * tracking; `subscribe(handler)` fires `handler` immediately with the current
+ * value and on every change until the returned unsubscribe is called.
+ */
+type ReadSignal<T> = {
+  readonly value: T; /** Read the current value without registering a dependency. */
+  peek(): T;
+  /**
+   * Subscribe to value changes. The handler is called synchronously with the
+   * current value on subscribe and on every change thereafter. Returns the
+   * unsubscribe function.
+   */
+  subscribe(handler: (value: T) => void): () => void;
+};
+/**
+ * Writable reactive value. `value` is assignable; `set(value)` is the
+ * functional equivalent; `update(fn)` reads (peek) and writes the result of
+ * `fn(previous)`.
+ */
+type Signal<T> = ReadSignal<T> & {
+  value: T;
+  set(value: T): void;
+  update(fn: (prev: T) => T): void;
+};
+/** A read-only derived signal — alias of `ReadSignal<T>`. */
+type Computed<T> = ReadSignal<T>;
+//#endregion
+//#region src/forms/types.d.ts
+type Validator<T> = (value: T, signal: AbortSignal) => string | null | Promise<string | null>;
+//#endregion
+//#region src/forms/form-types.d.ts
+type FormSchema = {
+  [key: string]: Field<any> | Form<any> | FieldArray<any>;
+};
+type FormValue<S extends FormSchema> = { [K in keyof S]: S[K] extends Field<infer T> ? T : S[K] extends Form<infer SS> ? FormValue<SS> : S[K] extends FieldArray<infer I> ? FieldArrayValue<I> : never };
+type FormErrors<S extends FormSchema> = { [K in keyof S]?: S[K] extends Field<any> ? string[] | undefined : S[K] extends Form<infer SS> ? FormErrors<SS> : S[K] extends FieldArray<infer I> ? Array<FieldArrayItemErrors<I> | undefined> : never };
+type FieldArrayValue<I> = I extends Field<infer T> ? T[] : I extends Form<infer S> ? FormValue<S>[] : never;
+type FieldArrayItemErrors<I> = I extends Field<any> ? string[] : I extends Form<infer S> ? FormErrors<S> : never;
+type ItemInitial<I> = I extends Field<infer T> ? T : I extends Form<infer S> ? DeepPartial<FormValue<S>> : never;
+type DeepPartial<T> = T extends object ? T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : { [K in keyof T]?: DeepPartial<T[K]> } : T;
+type FormValidator<S extends FormSchema> = Validator<FormValue<S>>;
+type FieldArrayValidator<I> = Validator<FieldArrayValue<I>>;
+type FormOptions<S extends FormSchema> = {
+  initial?: (() => DeepPartial<FormValue<S>> | undefined) | DeepPartial<FormValue<S>>;
+  validators?: FormValidator<S>[];
+};
+type FieldArrayOptions<I> = {
+  initial?: Array<ItemInitial<I>>;
+  validators?: FieldArrayValidator<I>[];
+};
+/**
+ * A nested form. Created via `ctx.form(schema, options?)`. `value` aggregates
+ * every leaf into the structurally-typed `FormValue<S>`; `errors` mirrors that
+ * shape with `string[] | undefined`. `flatErrors` is a flattened view useful
+ * for rendering a single error summary. Spec §8, §20.7.
+ *
+ * IMPORTANT: `Form.value` is a `ReadSignal<FormValue<S>>` while `Field.value`
+ * is `T` directly — different shapes. See `.wiki/pitfalls/field-value-shape.md`.
+ */
+type Form<S extends FormSchema> = {
+  readonly fields: { [K in keyof S]: S[K] };
+  readonly value: ReadSignal<FormValue<S>>;
+  readonly errors: ReadSignal<FormErrors<S>>;
+  readonly topLevelErrors: ReadSignal<string[]>;
+  readonly flatErrors: ReadSignal<Array<{
+    path: string;
+    errors: string[];
+  }>>;
+  readonly isValid: ReadSignal<boolean>;
+  readonly isDirty: ReadSignal<boolean>;
+  readonly touched: ReadSignal<boolean>;
+  readonly isValidating: ReadSignal<boolean>; /** Deep-merge a partial value into the form, batched. */
+  set(partial: DeepPartial<FormValue<S>>): void;
+  /**
+   * Re-seat the form's leaves from `partial` as their new initials —
+   * each leaf calls `setAsInitial(value)`, so `isDirty` stays false and a
+   * subsequent `reset()` returns *here*. Internal-ish but exported for
+   * `Form`-traversal code (nested-form initial application).
+   */
+  resetWithInitial(partial: DeepPartial<FormValue<S>>): void; /** Reset every leaf to its initial value. */
+  reset(): void; /** Mark every leaf as touched (so error messages appear). */
+  markAllTouched(): void; /** Re-run every leaf's validators. Resolves with true if all leaves are valid. */
+  validate(): Promise<boolean>; /** Idempotent. Called by the owning controller's dispose. */
+  dispose(): void;
+};
+/**
+ * A dynamically-sized list of `Field` or `Form` items. Created via
+ * `ctx.fieldArray(itemFactory, options?)`. The factory is invoked per
+ * insertion. Spec §8, §20.7.
+ */
+type FieldArray<I extends Field<any> | Form<any>> = {
+  readonly items: ReadSignal<ReadonlyArray<I>>;
+  readonly value: ReadSignal<FieldArrayValue<I>>;
+  readonly errors: ReadSignal<Array<FieldArrayItemErrors<I> | undefined>>;
+  readonly topLevelErrors: ReadSignal<string[]>;
+  readonly isValid: ReadSignal<boolean>;
+  readonly isDirty: ReadSignal<boolean>;
+  readonly touched: ReadSignal<boolean>;
+  readonly isValidating: ReadSignal<boolean>;
+  readonly size: ReadSignal<number>;
+  add(initial?: ItemInitial<I>): void;
+  insert(index: number, initial?: ItemInitial<I>): void;
+  remove(index: number): void;
+  move(from: number, to: number): void;
+  at(index: number): I | undefined;
+  clear(): void;
+  reset(): void;
+  markAllTouched(): void;
+  validate(): Promise<boolean>;
+  dispose(): void;
+};
+//#endregion
+//#region src/query/types.d.ts
+/** Lifecycle phase of an async resource. */
+type AsyncStatus = 'idle' | 'pending' | 'success' | 'error';
+/**
+ * The eight reactive signals + three actions a subscriber sees for any async
+ * resource (`LocalCache<T>` or a `Query` subscription). Spec §20.4.
+ *
+ * - `data` / `error` / `status` — current outcome.
+ * - `isLoading` — true only on the first pending fetch (no `data` yet).
+ * - `isFetching` — true on any pending fetch.
+ * - `isStale` — true when `staleTime` has elapsed since `lastUpdatedAt`.
+ * - `lastUpdatedAt` — epoch ms of last success.
+ * - `hasPendingMutations` — at least one mutation has a snapshot on this entry.
+ *
+ * Actions:
+ * - `refetch()` — force a fetch; resolves with the result.
+ * - `reset()` — clear `error` + `status` without re-fetching.
+ * - `firstValue()` — resolves on the first success after subscribe.
+ */
+type AsyncState<T> = {
+  data: ReadSignal<T | undefined>;
+  error: ReadSignal<unknown | undefined>;
+  status: ReadSignal<AsyncStatus>;
+  isLoading: ReadSignal<boolean>;
+  isFetching: ReadSignal<boolean>;
+  isStale: ReadSignal<boolean>;
+  lastUpdatedAt: ReadSignal<number | undefined>;
+  hasPendingMutations: ReadSignal<boolean>;
+  refetch: () => Promise<T>;
+  reset: () => void;
+  firstValue: () => Promise<T>;
+};
+/**
+ * Returned by `query.setData(...)` or `localCache.setData(...)`. Used by
+ * `mutation.onMutate` for optimistic-update rollback (spec §6.4).
+ *
+ * - `rollback()` restores the previous data state (and clears the
+ *   "pending mutation" flag on the entry if no other snapshots are live).
+ * - `finalize()` commits the snapshot as the new truth — no rollback,
+ *   `hasPendingMutations` clears once all live snapshots on the entry
+ *   are finalized or rolled back. The mutation runner calls this on
+ *   success; user code rarely needs to.
+ *
+ * Both are idempotent and mutually exclusive (calling one disables the
+ * other). Safe to call after the owning entry has been disposed.
+ */
+type Snapshot = {
+  rollback: () => void;
+  finalize: () => void;
+};
+/**
+ * A cache owned by one controller — no sharing across the tree. Returned by
+ * `ctx.cache(fetcher, options?)`. Disposed automatically with the controller.
+ */
+type LocalCache<T> = AsyncState<T> & {
+  /** Mark stale and trigger an immediate refetch. */invalidate(): void; /** Patch the current data. Returns a `Snapshot` for rollback. */
+  setData(updater: (prev: T | undefined) => T): Snapshot; /** Idempotent — also called when the owning controller disposes. */
+  dispose(): void;
+};
+/** One entry inside a `DehydratedState`. */
+type DehydratedEntry = {
+  key: readonly unknown[];
+  data: unknown;
+  lastUpdatedAt: number;
+};
+/**
+ * SSR-serializable snapshot of a root's `QueryClient`. Produced by
+ * `root.dehydrate()` on the server; consumed by
+ * `createRoot(def, { hydrate: state })` on the client. Spec §15, §20.9.
+ */
+type DehydratedState = {
+  version: 1;
+  entries: DehydratedEntry[];
+};
+/**
+ * Retry policy for queries and mutations. A number is a max-attempt count
+ * (default backoff). A function decides per-attempt (return `true` to retry).
+ */
+type RetryPolicy = number | ((attempt: number, error: unknown) => boolean);
+/** Backoff in ms. A number is constant delay; a function computes per-attempt. */
+type RetryDelay = number | ((attempt: number) => number);
+/**
+ * Per-fetch context: the `AbortSignal` to honor + the root's `deps`. Passed
+ * as the first argument to every `QuerySpec.fetcher` invocation so module-
+ * level queries can reach their dependencies without resorting to globals.
+ */
+type FetchCtx = {
+  signal: AbortSignal;
+  deps: AmbientDeps;
+};
+/**
+ * Configuration passed to `defineQuery({ ... })`. The `Args` tuple is what
+ * callers pass as cache keys and to the fetcher. Spec §20.4.
+ *
+ * The fetcher's first argument is a `FetchCtx` (signal + deps); positional
+ * cache args come after. This shape lets module-scoped queries read
+ * `ctx.deps.api` etc. — no `setApiForQuery(api)` module-level capture needed.
+ */
+type QuerySpec<Args extends unknown[], T> = {
+  key: (...args: Args) => unknown[];
+  fetcher: (ctx: FetchCtx, ...args: Args) => Promise<T>;
+  staleTime?: number;
+  gcTime?: number;
+  refetchInterval?: number;
+  refetchOnWindowFocus?: boolean;
+  refetchOnReconnect?: boolean;
+  keepPreviousData?: boolean;
+  retry?: RetryPolicy;
+  retryDelay?: RetryDelay;
+  /**
+   * Stable identifier used by `QueryClientPlugin`s (e.g. `@kontsedal/olas-cross-tab`)
+   * to locate the same query across tabs / processes / persistence layers.
+   * REQUIRED for queries with `crossTab: true`. SPEC §13.2.
+   *
+   * Don't auto-derive from `fetcher.name` or argument hashing — both are
+   * fragile under minification.
+   */
+  queryId?: string;
+  /**
+   * Opt this query into cross-tab cache sync (`@kontsedal/olas-cross-tab`). No effect
+   * without a `queryId` and without a plugin installed. SPEC §13.2.
+   */
+  crossTab?: boolean;
+};
+/**
+ * A module-scoped shared query handle. Bind a subscriber via
+ * `ctx.use(query, () => [...args])`. The same `Query` value can be used by
+ * many controllers across many roots — each root has its own cache.
+ */
+type Query<Args extends unknown[], T> = {
+  readonly __olas: 'query'; /** Mark a specific keyed entry stale + trigger refetch if any subscribers. */
+  invalidate(...args: Args): void; /** Mark every keyed entry stale + trigger refetch on all subscribers. */
+  invalidateAll(): void; /** Patch the current data for a specific key. Returns a `Snapshot` for rollback. */
+  setData(...args: [...Args, updater: (prev: T | undefined) => T]): Snapshot; /** Eagerly fetch into the cache without subscribing. */
+  prefetch(...args: Args): Promise<T>;
+};
+/** What `ctx.use(query, ...)` returns. Alias of `AsyncState<T>`. */
+type QuerySubscription<T> = AsyncState<T>;
+/**
+ * Options passed to `ctx.use(query, opts)` to control the subscription
+ * (reactive key, enabled-gating). The `key` thunk reads signals — re-evaluating
+ * when they change re-keys the subscription.
+ */
+type UseOptions<Args extends readonly unknown[]> = {
+  key?: () => Args;
+  enabled?: () => boolean;
+};
+//#endregion
+//#region src/query/infinite.d.ts
+/**
+ * Configuration for `defineInfiniteQuery({ ... })`. Spec §5.7, §20.4.
+ *
+ * - `getNextPageParam(lastPage, allPages)` returns the param for the next
+ *   page, or `null` when there's no more.
+ * - `getPreviousPageParam` (optional) enables bidirectional infinite lists.
+ * - `itemsOf(page)` (optional) flattens pages into items for the
+ *   `subscription.flat` convenience signal.
+ */
+type InfiniteFetchCtx<PageParam> = {
+  pageParam: PageParam;
+  signal: AbortSignal;
+  deps: AmbientDeps;
+};
+type InfiniteQuerySpec<Args extends unknown[], PageParam, TPage, TItem = TPage> = {
+  key: (...args: Args) => unknown[];
+  /**
+   * Fetcher receives an `InfiniteFetchCtx` (pageParam + signal + deps) as
+   * the first arg and positional cache args after. See `FetchCtx` for the
+   * regular-query analogue.
+   */
+  fetcher: (ctx: InfiniteFetchCtx<PageParam>, ...args: Args) => Promise<TPage>;
+  initialPageParam: PageParam;
+  getNextPageParam: (lastPage: TPage, allPages: TPage[]) => PageParam | null;
+  getPreviousPageParam?: (firstPage: TPage, allPages: TPage[]) => PageParam | null;
+  itemsOf?: (page: TPage) => TItem[];
+  staleTime?: number;
+  gcTime?: number;
+  refetchInterval?: number;
+  keepPreviousData?: boolean;
+  retry?: RetryPolicy;
+  retryDelay?: RetryDelay;
+  /**
+   * Stable identifier used by `QueryClientPlugin`s (`@kontsedal/olas-cross-tab`,
+   * etc.). Infinite queries do NOT propagate cross-tab in v1 — the
+   * page-array payload is too heavy to be a safe default — but the field is
+   * accepted for forward compatibility. SPEC §13.2.
+   */
+  queryId?: string;
+  /**
+   * Opt into cross-tab sync. No effect for infinite queries in v1 (see
+   * `queryId` doc above).
+   */
+  crossTab?: boolean;
+};
+/**
+ * Module-scoped handle for a paginated query. Mirrors `Query<Args, TPage[]>`
+ * with paginated `setData` semantics.
+ */
+type InfiniteQuery<Args extends unknown[], TPage, _TItem> = {
+  readonly __olas: 'infiniteQuery';
+  invalidate(...args: Args): void;
+  invalidateAll(): void;
+  setData(...args: [...Args, updater: (prev: TPage[] | undefined) => TPage[]]): {
+    rollback: () => void;
+  };
+  prefetch(...args: Args): Promise<TPage>;
+};
+/**
+ * What `ctx.use(infiniteQuery, ...)` returns. Extends `AsyncState<TPage[]>`
+ * with paginated controls: `fetchNextPage` / `fetchPreviousPage`,
+ * `hasNextPage` / `hasPreviousPage`, and per-direction `isFetching` signals.
+ *
+ * `flat` is a convenience: present when the query spec provides `itemsOf` —
+ * otherwise it's an empty array.
+ */
+type InfiniteQuerySubscription<TPage, TItem> = AsyncState<TPage[]> & {
+  pages: ReadSignal<TPage[]>;
+  flat: ReadSignal<TItem[]>;
+  hasNextPage: ReadSignal<boolean>;
+  hasPreviousPage: ReadSignal<boolean>;
+  isFetchingNextPage: ReadSignal<boolean>;
+  isFetchingPreviousPage: ReadSignal<boolean>;
+  fetchNextPage: () => Promise<void>;
+  fetchPreviousPage: () => Promise<void>;
+};
+//#endregion
+//#region src/devtools.d.ts
+/**
+ * Discriminated union of devtools events emitted by a root via
+ * `root.__debug.subscribe(handler)`. Spec §20.9. Adding new variants is
+ * non-breaking — consumers `switch` on `type` and ignore unknowns.
+ */
+type DebugEvent = {
+  type: 'controller:constructed';
+  path: readonly string[];
+  props: unknown;
+} | {
+  type: 'controller:suspended';
+  path: readonly string[];
+} | {
+  type: 'controller:resumed';
+  path: readonly string[];
+} | {
+  type: 'controller:disposed';
+  path: readonly string[];
+} | {
+  type: 'cache:subscribed';
+  queryKey: readonly unknown[];
+  subscriberPath: readonly string[];
+} | {
+  type: 'cache:fetch-start';
+  queryKey: readonly unknown[];
+} | {
+  type: 'cache:fetch-success';
+  queryKey: readonly unknown[];
+  durationMs: number;
+} | {
+  type: 'cache:fetch-error';
+  queryKey: readonly unknown[];
+  error: unknown;
+  durationMs: number;
+} | {
+  type: 'cache:invalidated';
+  queryKey: readonly unknown[];
+} | {
+  type: 'cache:gc';
+  queryKey: readonly unknown[];
+} | {
+  type: 'mutation:run';
+  path: readonly string[];
+  name?: string;
+  vars: unknown;
+} | {
+  type: 'mutation:success';
+  path: readonly string[];
+  name?: string;
+  result: unknown;
+} | {
+  type: 'mutation:error';
+  path: readonly string[];
+  name?: string;
+  error: unknown;
+} | {
+  type: 'mutation:rollback';
+  path: readonly string[];
+  name?: string;
+} | {
+  type: 'field:validated';
+  path: readonly string[];
+  field: string;
+  valid: boolean;
+  errors: string[];
+};
+/**
+ * Snapshot of one live cache entry — produced by `root.__debug.queryEntries()`
+ * so devtools panels can show *current data*, not just past fetch events.
+ */
+type DebugCacheEntry = {
+  key: readonly unknown[];
+  status: 'idle' | 'pending' | 'success' | 'error';
+  data: unknown;
+  error: unknown;
+  lastUpdatedAt: number | undefined;
+  isStale: boolean;
+  isFetching: boolean;
+  hasPendingMutations: boolean;
+};
+/**
+ * The shape of `root.__debug`. Subscribe to receive every `DebugEvent` until
+ * the returned unsubscribe is called.
+ *
+ * The bus replays a snapshot of the *live controller tree* to every new
+ * subscriber synchronously inside `subscribe(...)` — so a panel that mounts
+ * after `createRoot()` sees the existing tree immediately, not just future
+ * events. Event types other than `controller:*` are not buffered.
+ *
+ * `queryEntries()` returns a fresh inspector snapshot — current state of
+ * every cached entry. Useful for "what's in the cache right now?" views.
+ */
+type DebugBus = {
+  subscribe(handler: (event: DebugEvent) => void): () => void;
+  queryEntries(): DebugCacheEntry[];
+};
+//#endregion
+//#region src/query/mutation.d.ts
+/**
+ * How concurrent calls to `mutation.run(...)` interact:
+ * - `parallel` (default): every call runs concurrently.
+ * - `latest-wins`: a new call aborts any in-flight previous call (`AbortSignal` fires).
+ * - `serial`: calls queue and run one at a time in order.
+ *
+ * Spec §6.3.
+ */
+type MutationConcurrency = 'parallel' | 'latest-wins' | 'serial';
+/**
+ * The configuration object passed to `ctx.mutation(spec)`. See spec §20.5 for
+ * the full lifecycle semantics. `onMutate` may return a `Snapshot` (from
+ * `query.setData(...)`) to enable automatic rollback on error.
+ */
+type MutationSpec<V, R> = {
+  /**
+   * A short human-readable name. Surfaces in the devtools mutation log so the
+   * user sees `moveCard` instead of just the controller path. Strongly
+   * recommended in app code; cosmetic only — no runtime semantics depend on it.
+   */
+  name?: string; /** The actual write. Receives the user-supplied vars and an `AbortSignal`. */
+  mutate: (vars: V, signal: AbortSignal) => Promise<R>;
+  /**
+   * Runs before `mutate`. Return a `Snapshot` from `query.setData(...)` to
+   * apply an optimistic update; the snapshot is rolled back on error.
+   */
+  onMutate?: (vars: V) => Snapshot | void;
+  onSuccess?: (result: R, vars: V) => void;
+  onError?: (err: unknown, vars: V, snapshot: Snapshot | undefined) => void;
+  onSettled?: (result: R | undefined, err: unknown | undefined, vars: V) => void;
+  concurrency?: MutationConcurrency;
+  retry?: RetryPolicy;
+  retryDelay?: RetryDelay;
+};
+/**
+ * A running mutation. Created via `ctx.mutation(spec)` — the controller owns
+ * its lifetime. Each `run(vars)` returns a Promise; the four signals reflect
+ * the last-resolved run for UI binding.
+ *
+ * Spec §6, §20.5.
+ */
+/**
+ * Call signature for `mutation.run`:
+ *  - When `V` is `void` → no args. (`mutation.run()`)
+ *  - When `V` was not constrained (default-inferred as `unknown`) → optional
+ *    arg. Lets `ctx.mutation({ mutate: async () => 1 })` call `run()` *or*
+ *    `run(anything)` without a type error.
+ *  - Otherwise → arg required. (`mutation.run(vars)`)
+ *
+ * Defined as a variadic-tuple conditional so consumers see the right shape
+ * without writing `run(undefined as unknown as void)`.
+ */
+type MutationRun<V, R> = (...args: unknown extends V ? [V?] : [V] extends [void] ? [] : [V]) => Promise<R>;
+type Mutation<V, R> = {
+  /** Trigger a run. Returns a Promise that resolves with the mutate result. */run: MutationRun<V, R>;
+  data: ReadSignal<R | undefined>;
+  error: ReadSignal<unknown | undefined>;
+  isPending: ReadSignal<boolean>;
+  lastVariables: ReadSignal<V | undefined>; /** Clear `data` / `error` / `lastVariables` without aborting in-flight runs. */
+  reset(): void; /** Abort in-flight runs and tear down. Idempotent. Called by the parent controller's dispose. */
+  dispose(): void;
+};
+//#endregion
+//#region src/query/plugin.d.ts
+/**
+ * `QueryClientPlugin` — a slot for layered cache concerns (cross-tab sync,
+ * server-push patches, persistence-like layers) that need to observe
+ * `setData` / `invalidate` / `gc` and apply remote writes back into the
+ * cache without re-triggering their own outbound side-effects.
+ *
+ * Plugins are installed via `RootOptions.plugins[]`; lifecycle is bound to
+ * the root's `QueryClient` (`init` is called once after construction;
+ * `dispose` is called from `QueryClient.dispose`).
+ *
+ * SPEC §13.2.
+ */
+/**
+ * Surface the plugin gets at `init` time. Used to push remote-originated
+ * cache writes through the normal `setData`/`invalidate` paths without
+ * triggering the plugin's own outbound hooks for those writes (the inbound
+ * writes are marked `isRemote: true` and rebroadcast must be skipped).
+ *
+ * `subscribedKeys(queryId)` walks the per-root entry registry for the
+ * matching query and returns every bound entry's `keyArgs`. Cross-tab
+ * plugins use this to scope outbound traffic (e.g. only echo invalidations
+ * for queries the local tab actually has entries for).
+ */
+type QueryClientPluginApi = {
+  /**
+   * Apply a remote snapshot. The plugin's own `onSetData` IS fired for the
+   * resulting cache write, but the event carries `isRemote: true` — plugins
+   * MUST skip rebroadcast in that case.
+   */
+  applyRemoteSetData(queryId: string, keyArgs: readonly unknown[], data: unknown): void;
+  applyRemoteInvalidate(queryId: string, keyArgs: readonly unknown[]): void;
+  /**
+   * Snapshot of currently bound entry keys for a query (by `queryId`). Empty
+   * array when the query isn't registered, has no client entries, or the
+   * `queryId` doesn't match any registered query.
+   */
+  subscribedKeys(queryId: string): readonly (readonly unknown[])[];
+};
+type SetDataEvent = {
+  queryId: string;
+  keyArgs: readonly unknown[];
+  data: unknown;
+  /**
+   * `'data'` for regular queries, `'infinite'` for paginated queries.
+   * Cross-tab plugins skip `'infinite'` in v1 — page-array payloads are
+   * too heavy to be a safe default.
+   */
+  kind: 'data' | 'infinite';
+  /**
+   * True iff this write originated from `applyRemoteSetData`. Plugins MUST
+   * skip rebroadcast in that case — otherwise the message would echo back.
+   */
+  isRemote: boolean;
+};
+type InvalidateEvent = {
+  queryId: string;
+  keyArgs: readonly unknown[];
+  kind: 'data' | 'infinite';
+  isRemote: boolean;
+};
+type GcEvent = {
+  queryId: string;
+  keyArgs: readonly unknown[];
+  kind: 'data' | 'infinite';
+};
+/**
+ * Plugin contract. Every hook is optional. Hooks are wrapped in try/catch
+ * by `QueryClient`; thrown exceptions are routed through the root's
+ * `onError` handler with `kind: 'plugin'`.
+ */
+type QueryClientPlugin = {
+  /**
+   * Called once after the `QueryClient` is constructed. Use it to wire up
+   * transport listeners and capture the `QueryClientPluginApi`.
+   */
+  init?(api: QueryClientPluginApi): void;
+  onSetData?(event: SetDataEvent): void;
+  onInvalidate?(event: InvalidateEvent): void;
+  onGc?(event: GcEvent): void; /** Called from `QueryClient.dispose`. Tear down transports / listeners here. */
+  dispose?(): void;
+};
+/**
+ * Shape of values stored in the `queryId → Query` registry. Either a
+ * regular `Query` or an `InfiniteQuery`, both branded by `__olas`.
+ */
+type RegisteredQuery = {
+  readonly __olas: 'query' | 'infiniteQuery';
+  readonly __spec: {
+    queryId?: string;
+    crossTab?: boolean;
+  };
+};
+/**
+ * Look up a query by its declared `queryId`. Returns `undefined` when no
+ * query with that id has been defined yet (e.g. the module isn't imported
+ * in the receiving tab).
+ */
+declare function lookupRegisteredQuery(queryId: string): RegisteredQuery | undefined;
+//#endregion
+//#region src/scope.d.ts
+/**
+ * Typed cross-tree data slot. Provided by an ancestor via `ctx.provide(scope, value)`
+ * and consumed anywhere in its subtree via `ctx.inject(scope)`. Defined at module
+ * scope so the identity is stable across calls. See spec §10.3.
+ */
+type Scope<T> = {
+  readonly __olas: 'scope'; /** Per-scope identity; matches across `provide` / `inject`. */
+  readonly __id: symbol; /** Optional human-readable name (used in error messages). */
+  readonly name?: string; /** Default value used when no provider exists; `undefined` if none was set. */
+  readonly default?: T; /** True iff `defineScope` was called with a `default` (even `default: undefined`). */
+  readonly hasDefault: boolean;
+  readonly __t?: T;
+};
+type ScopeOptions<T> = {
+  default?: T;
+  name?: string;
+};
+/**
+ * Create a scope. The returned value is the typed handle passed to
+ * `ctx.provide(scope, value)` and `ctx.inject(scope)`. Identity is keyed by
+ * an internal symbol so two `defineScope()` calls — even with identical
+ * options — yield distinct scopes.
+ */
+declare function defineScope<T>(options?: ScopeOptions<T>): Scope<T>;
+//#endregion
+//#region src/controller/types.d.ts
+/**
+ * App-wide deps available on every controller's `ctx.deps`.
+ *
+ * Default shape carries an index signature so untyped reads compile (as
+ * `unknown`). Users augment this interface in their app to add typed services:
+ *
+ * ```ts
+ * declare module '@kontsedal/olas-core' {
+ *   interface AmbientDeps {
+ *     api: ApiClient
+ *     session: SessionStore
+ *   }
+ * }
+ * ```
+ */
+interface AmbientDeps {
+  [key: string]: unknown;
+}
+/**
+ * A reactive form field. Extends `ReadSignal<T>` for the current value, plus
+ * five signals for state (errors / isValid / isDirty / touched / isValidating)
+ * and four methods (`set`, `reset`, `markTouched`, `revalidate`). Created via
+ * `ctx.field(initial, validators?)`. Spec §8, §20.7.
+ */
+type Field<T> = ReadSignal<T> & {
+  errors: ReadSignal<string[]>;
+  isValid: ReadSignal<boolean>;
+  isDirty: ReadSignal<boolean>;
+  touched: ReadSignal<boolean>;
+  isValidating: ReadSignal<boolean>;
+  set(value: T): void;
+  /**
+   * Reseat the field as if this value had been its constructor `initial`:
+   * writes the value, re-anchors `reset()`'s target, leaves `isDirty` false.
+   * `Form` uses this when applying its own `initial` (constructor + reset),
+   * so a form populated from server data isn't born dirty. Useful for any
+   * "load this value as the new baseline" pattern.
+   */
+  setAsInitial(value: T): void;
+  reset(): void;
+  markTouched(): void;
+  revalidate(): Promise<boolean>; /** Idempotent. Called by the owning controller's dispose. */
+  dispose(): void;
+};
+/**
+ * The handle returned by `defineController(...)`. Pass it to `createRoot(...)`
+ * or `ctx.child(...)` to instantiate. Phantom types preserve `Props` / `Api`
+ * for inference via `CtrlProps<C>` / `CtrlApi<C>`.
+ */
+type ControllerDef<Props, Api> = {
+  readonly __olas: 'controller';
+  readonly __types?: {
+    props: Props;
+    api: Api;
+  };
+};
+/** Extract a controller's Props type. */
+type CtrlProps<C> = C extends ControllerDef<infer P, unknown> ? P : never;
+/** Extract a controller's Api type. */
+type CtrlApi<C> = C extends ControllerDef<unknown, infer A> ? A : never;
+/**
+ * `ctx` is the lifecycle-bound surface every controller factory receives.
+ * Every primitive constructed through `ctx` is owned by the controller and
+ * disposed when the controller disposes.
+ *
+ * Phase 3 surface — caches, mutations, forms, collections, scopes, etc.
+ * land in later phases.
+ */
+type Ctx<TDeps = AmbientDeps> = {
+  cache<T>(fetcher: (signal: AbortSignal) => Promise<T>, options?: {
+    key?: () => readonly unknown[];
+    staleTime?: number;
+    keepPreviousData?: boolean;
+    initialData?: T | undefined;
+  }): LocalCache<T>;
+  use<Args extends unknown[], T>(source: Query<Args, T>, keyOrOptions?: (() => Args) | UseOptions<Args>): QuerySubscription<T>;
+  use<Args extends unknown[], TPage, TItem>(source: InfiniteQuery<Args, TPage, TItem>, keyOrOptions?: (() => Args) | UseOptions<Args>): InfiniteQuerySubscription<TPage, TItem>;
+  mutation<V, R>(spec: MutationSpec<V, R>): Mutation<V, R>;
+  emitter<T = void>(): Emitter<T>;
+  field<T>(initial: T, validators?: ReadonlyArray<Validator<T>>): Field<T>;
+  form<S extends FormSchema>(schema: S, options?: FormOptions<S>): Form<S>;
+  fieldArray<I extends Field<any> | Form<any>>(itemFactory: (initial?: ItemInitial<I>) => I, options?: FieldArrayOptions<I>): FieldArray<I>;
+  child<Props, Api>(def: ControllerDef<Props, Api>, props: Props, options?: {
+    deps?: Partial<TDeps>;
+  }): Api;
+  /**
+   * Like `child(...)` but additionally returns a `dispose()` handle so the
+   * parent can tear down this specific sub-tree early — e.g. when the user
+   * closes a details panel. The child is still disposed automatically when
+   * the parent disposes; `dispose()` is idempotent and only earlies the
+   * teardown. Useful for "openable" sub-controllers whose lifetime is driven
+   * by a user gesture rather than the parent's lifetime alone.
+   */
+  attach<Props, Api>(def: ControllerDef<Props, Api>, props: Props, options?: {
+    deps?: Partial<TDeps>;
+  }): {
+    api: Api;
+    dispose: () => void;
+  };
+  effect(fn: () => void | (() => void)): void;
+  on<T>(emitter: Emitter<T>, handler: (value: T) => void): void;
+  provide<T>(scope: Scope<T>, value: T): void;
+  inject<T>(scope: Scope<T>): T;
+  onDispose(fn: () => void): void;
+  onSuspend(fn: () => void): void;
+  onResume(fn: () => void): void;
+  readonly deps: TDeps;
+};
+/**
+ * Configuration passed to `createRoot(def, options)`. `deps` is required and
+ * available everywhere as `ctx.deps`. `onError` receives errors from effects,
+ * mutations, caches, emitter handlers, and construction. `hydrate` replays a
+ * `DehydratedState` produced on the server. Spec §20.8.
+ */
+type RootOptions<TDeps> = {
+  deps: TDeps;
+  onError?: (err: unknown, context: ErrorContext) => void;
+  hydrate?: DehydratedState; /** Default for queries that don't set `refetchOnWindowFocus` on their spec (§5.9). */
+  refetchOnWindowFocus?: boolean; /** Default for queries that don't set `refetchOnReconnect` on their spec (§5.9). */
+  refetchOnReconnect?: boolean;
+  /**
+   * `QueryClientPlugin`s — cross-tab sync, server-push patches, etc.
+   * Installed when the root's `QueryClient` is constructed; disposed when
+   * the root disposes. SPEC §13.2.
+   */
+  plugins?: QueryClientPlugin[];
+};
+/**
+ * The root's public surface: the controller's `Api` plus lifecycle controls
+ * (`dispose`, `suspend`, `resume`), SSR (`dehydrate`, `waitForIdle`), and
+ * devtools (`__debug`). Spec §20.8.
+ */
+type Root<Api> = Api & {
+  dispose(): void;
+  suspend(options?: {
+    maxIdle?: number;
+  }): void;
+  resume(): void;
+  dehydrate(): DehydratedState;
+  waitForIdle(): Promise<void>;
+  readonly __debug: DebugBus;
+};
+//#endregion
+export { Validator as $, DehydratedEntry as A, DeepPartial as B, DebugCacheEntry as C, InfiniteQuerySubscription as D, InfiniteQuerySpec as E, QuerySubscription as F, FieldArrayValue as G, FieldArrayItemErrors as H, RetryDelay as I, FormOptions as J, Form as K, RetryPolicy as L, LocalCache as M, Query as N, AsyncState as O, QuerySpec as P, ItemInitial as Q, Snapshot as R, DebugBus as S, InfiniteQuery as T, FieldArrayOptions as U, FieldArray as V, FieldArrayValidator as W, FormValidator as X, FormSchema as Y, FormValue as Z, SetDataEvent as _, Ctx as a, createEmitter as at, MutationConcurrency as b, RootOptions as c, defineScope as d, Computed as et, GcEvent as f, RegisteredQuery as g, QueryClientPluginApi as h, CtrlProps as i, Emitter as it, DehydratedState as j, AsyncStatus as k, Scope as l, QueryClientPlugin as m, ControllerDef as n, Signal as nt, Field as o, InvalidateEvent as p, FormErrors as q, CtrlApi as r, ErrorContext as rt, Root as s, AmbientDeps as t, ReadSignal as tt, ScopeOptions as u, lookupRegisteredQuery as v, DebugEvent as w, MutationSpec as x, Mutation as y, UseOptions as z };
+//# sourceMappingURL=types-CAMgqCMz.d.mts.map