@gyral/core

npm install @gyral/core

function call(selector: string, method: string, ...args: readonly unknown[]): Command<never>;

Start: (s) => [{ ...s, playing: true }, [call('video', 'play')]]
Join: (s, m) => [s, [call('room-stage', 'join', m.room)]]

function changed<S>(store: StoreRef<S>, msg: StoreChanged): {
    readonly state: S;
    readonly prev: S;
} | undefined;

function child<O extends Tagged, E extends Element, M>(source: ChildSource<O, E>, toMsg: (output: O, el: E) => M | undefined): (input: IntentInput) => ReturnType<IntentParser<M>>;

const Folder: GyralElementClass<State, Msg, Props, Out> = define()('x-folder', {
  intent: { Child: child(() => Folder, (out, el) => …) }, …
});

function command<I, O, E, const MS = never, const MF = MS>(driver: Driver<I, O, E>, input: I, handlers?: CommandHandlers<O, E, MS, MF>): Command<MS | MF>;

function componentsReady(): Promise<void>;

function css(strings: TemplateStringsArray, ...values: readonly CssValue[]): StyleSource;

function define(): <S, M extends Tagged = never, P extends object = object, N extends string = never>(tag: string, spec: ComponentSpec<S, M, P, N>) => GyralElementClass<S, M, P, never, N>;
function define<S, M extends Tagged = never, P extends object = object, O extends Tagged = never>(): Definer<S, M, P, O>;

define<State, Msg>()('x-counter', { init, intent: { Increment: … }, update, view })

function defineDriver<I, O, E = unknown>(spec: Driver<I, O, E> | DriverToken<E> | string): Driver<I, O, E>;

function defineForm<Schema extends StandardSchemaV1>(schema: Schema, options?: FormOptions<Schema>): FormDefinition<Schema>;

function defineHook<A extends readonly unknown[]>(spec: HookSpec<A>): (...args: A) => HookResult<A>;

function defineStore<S, M extends Tagged>(name: string, spec: StoreSpec<S, M>): Store<S, M>;

function each<T>(items: readonly T[], key: (item: T) => string | number, row: (item: T) => ChildValue): ListResult;
function each<T, P>(items: readonly T[], key: (item: T) => string | number, row: (item: T, picked: P) => ChildValue, pick: (item: T) => P): ListResult;

function field<Schema extends StandardSchemaV1, M>(schema: Schema, toMsg: (value: Out<Schema>) => M | undefined): (input: IntentInput) => ReturnType<IntentParser<M>>;

function fieldErrors(issues: readonly FieldIssue[]): Readonly<Record<string, readonly string[]>>;

function focus(selector: string, options?: FocusOptions): Command<never>;

NextPage: (s, m) => [{ ...s, page: m.page }, [focus('h2', { preventScroll: true })]]

function form<Schema extends StandardSchemaV1, M>(definition: FormDefinition<Schema> | Schema, toMsg: (data: Out<Schema>, formData: FormData) => M | undefined): (input: IntentInput) => ReturnType<IntentParser<M>>;

const html: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult

function intentsOf<C extends {
    readonly intentNames?: string;
}>(): IntentNames<NonNullable<C['intentNames']>>;

const i = intentsOf<typeof TodoList>();
const Row = (t: Todo): TemplateResult => html`<input value=${t.id} data-intent=${i.Toggle} />`;

const invalid: (errors?: Errors) => HookResult<[errors?: Errors]>

<input name="email" ${invalid(s.errors.email)} />

function keyed(key: string | number, value: ChildValue): ListResult;

function outputs<O extends Tagged>(): (output: O) => Command<never>;

type Out = { readonly _tag: 'Picked'; readonly id: number };
const emit = outputs<Out>();
// in update: Pick: (s, m) => [s, [emit({ _tag: 'Picked', id: m.id })]]

function provideDrivers(element: Element, drivers: DriverOverrides): () => void;

function raw(html: string): RawResult;

function retry<I, O, E>(driver: Driver<I, O, E>, policy: RetryPolicy<E>): Driver<I, O, E>;

const api = retry(makeHttpDriver({ baseUrl: '/api', timeoutMs: 8000 }), {
  times: 3, delayMs: 300, backoff: 'exponential', jitter: true, retryIf: retryableHttpError,
});
const feed = retry(subscription('feed', connect), { times: Infinity, delayMs: 1000 });

function send<S, M extends Tagged>(store: Store<S, M>, msg: NoInfer<M>): Command<never>;

function settled(): Promise<void>;

el.send({ _tag: 'Increment' });
await settled();

function subscription<O, I = undefined, E = unknown>(name: string, subscribe: (emit: (value: O) => void, ctx: SubscriptionContext<I>) => Unsubscribe, options?: SubscriptionOptions<E>): Driver<I, O, E>;

const cart = subscription<CartState>('cart', (emit) => {
  emit(reduxStore.getState());
  return reduxStore.subscribe(() => emit(reduxStore.getState()));
});
// subscriptions: () => [command(cart, undefined, { onSuccess: (c) => ({ _tag: 'Cart', c }) })]

const svg: (strings: TemplateStringsArray, ...values: unknown[]) => TemplateResult

class GyralError extends Error {
  readonly name = "GyralError";
  readonly component: string | undefined;
  readonly phase: ErrorPhase;
  readonly msg: string | undefined;
  constructor(phase: ErrorPhase, text: string, cause: unknown, component?: string, msg?: string);
}

const nothing: typeof nothing

const OUTPUT_EVENT: "gyral-output"

const prop: { readonly string: Scalar<string>; readonly number: Scalar<number>; readonly boolean: <O extends boolean = boolean>(opts?: (Common & { readonly schema?: Schema<O> | undefined; } & { readonly default?: NoInfer<O> | undefined; }) | undefined) => Prop<O>; readonly json: WithSchema; readonly value: WithSchema; }

type AnyDriver = Driver<never, unknown>;

interface AnyStore {
    readonly name: string;
    instance(initial?: never): AnyStoreInstance;
    checkSeed(seed: unknown): SeedCheck<unknown>;
}

interface AnyStoreInstance {
    readonly store: AnyStore;
    readonly state: unknown;
    send(msg: never): void;
    subscribe(listener: (state: unknown, prev: unknown) => void): () => void;
    dispose(): void;
    /**
     * Called by the registry that holds this instance, so the store's `send(other, msg)`
     * commands reach `other`'s instance in the same scope.
     */
    bindScope?(resolve: StoreResolver): void;
}

interface CallInput {
    readonly selector: string;
    readonly method: string;
    readonly args: readonly unknown[];
}

type ChildSource<O extends Tagged, E extends Element> = OutputSource<O, E> | (() => OutputSource<O, E>);

type ChildValue = string | number | boolean | null | undefined | typeof nothing | TemplateResult | ListResult | RawResult | readonly ChildValue[];

interface Command<M> {
    readonly driver: AnyDriver;
    readonly input: unknown;
    /** Concurrency lane. Default: the driver's name. */
    readonly key?: string;
    readonly concurrency?: Concurrency;
    readonly onSuccess: (output: unknown) => M | undefined;
    /** If omitted, a failure is reported to the error channel (ADR 0024, G0041). */
    readonly onFailure?: (error: unknown) => M | undefined;
}

interface CommandHandlers<O, E, MS, MF = MS> {
    readonly onSuccess?: (output: O) => MS | undefined;
    readonly onFailure?: (error: E) => MF | undefined;
    readonly key?: string;
    readonly concurrency?: Concurrency;
}

interface CommandInfo {
    /** The command, e.g. `--clear`. */
    readonly command: string;
    /** The invoker (the button) that sent it. */
    readonly source: Element | undefined;
}

type ComponentSpec<S, M extends Tagged, P, N extends string = string> = SpecBody<S, M, P, N> & IntentField<S, M, P, N> & UpdateField<S, M, P> & InitField<S, M, P>;

type Concurrency = 'merge' | 'switch' | 'exhaust' | 'queue';

type CssValue = string | number | StyleSource;

interface Ctx<P> {
    /** Props from above. */
    readonly props: P;
    /** Stores from the side: `read(cart).lines`. The store must be in `spec.stores`. */
    readonly read: StoreReader;
}

type Definer<S, M extends Tagged, P extends object, O extends Tagged> = <N extends string = never>(tag: string, spec: ComponentSpec<S, M, P, N>) => GyralElementClass<S, M, P, O, N>;

interface Driver<I, O, E = unknown> {
    readonly name: string;
    readonly run: (input: I, ctx: DriverContext<O>) => O | Promise<O>;
    /** Default policy for this driver's commands. Default `'merge'`. */
    readonly concurrency?: Concurrency;
    /** Turns a thrown or rejected value into this driver's typed error. */
    readonly toError?: (cause: unknown) => E;
}

interface DriverContext<O = unknown> {
    /** Aborts when the command is switched away or its component disconnects. */
    readonly signal: AbortSignal;
    /**
     * Delivers an extra result while the command runs (streaming drivers: routers, timers,
     * sockets). Each value goes through the command's `onSuccess`. Ignored once the command
     * has settled or been aborted. A streaming `run` usually never resolves; abort ends it.
     */
    readonly emit: (output: O) => void;
}

type DriverOverrides = Readonly<Record<string, AnyDriver>>;

interface DriverToken<E = unknown> {
    readonly name: string;
    readonly concurrency?: Concurrency;
    readonly toError?: (cause: unknown) => E;
}

interface Errored {
    readonly _tag: 'Errored';
    readonly phase: 'update' | 'parse' | 'command';
    readonly error: GyralError;
}

type ErrorPhase = 'init' | 'update' | 'view' | 'parse' | 'command' | 'hook' | 'store' | 'subscribe';

interface FieldIssue {
    readonly path: string;
    readonly message: string;
}

type FieldName<Schema extends StandardSchemaV1> = In<Schema> extends Readonly<Record<string, unknown>> ? keyof In<Schema> & string : string;

interface FocusOptions {
    /** Don't scroll the element into view (default `false`: the browser scrolls if needed). */
    readonly preventScroll?: boolean;
    /** Also select the text of an input or textarea. */
    readonly select?: boolean;
    /**
     * If nothing matches after this render, keep the request and focus the target as soon as a
     * later render of this component produces it; a newer `focus()` from the component replaces
     * it, and after one second it gives up with the usual warning. `settled()` doesn't wait for it.
     */
    readonly wait?: boolean;
}

interface FormAssociation<S, P> {
    readonly value: (state: S, ctx: Ctx<P>) => FormControlValue;
    readonly state?: (state: S, ctx: Ctx<P>) => FormControlValue;
    readonly validity?: (state: S, ctx: Ctx<P>) => FormControlValidity | undefined;
}

interface FormControlValidity {
    readonly flags: ValidityStateFlags;
    readonly message: string;
    readonly anchor?: string;
}

type FormControlValue = string | File | FormData | null;

interface FormDefinition<Schema extends StandardSchemaV1> {
    readonly _tag: 'FormDefinition';
    readonly schema: Schema;
    /** The fields listed as secret (names containing `password`, `passcode`, `csrf` or `xsrf` are secret too). */
    readonly secret: readonly string[];
    /**
     * Validates submitted form data exactly as `form()` does; the server's `formAction` uses it,
     * so both paths produce the same `IntentRejected` (`intent` defaults to `''`).
     */
    readonly validate: (data: FormData, intent?: string) => FormResult<Out<Schema>> | Promise<FormResult<Out<Schema>>>;
    /** The submitted text values without secrets: what a re-rendered form may show again. */
    readonly values: (data: FormData) => FormValues<Schema>;
}

interface FormDisabled {
    readonly _tag: 'FormDisabled';
    readonly disabled: boolean;
}

type FormFields = Readonly<Record<string, string | readonly string[]>>;

interface FormOptions<Schema extends StandardSchemaV1> {
    /**
     * Fields whose submitted values are never sent back: not in `IntentRejected.values`, not in
     * `values()`, not in the devtools timeline. Any posted field name may be listed, including
     * fields outside the schema. Names containing `password`, `passcode`, `csrf` or `xsrf` are
     * secret without being listed (the browser never restores a password field either, and a
     * CSRF token must come fresh from the server, not from the echo).
     */
    readonly secret?: readonly (FieldName<Schema> | (string & {}))[];
}

interface FormReset {
    readonly _tag: 'FormReset';
}

type FormResult<T> = {
    readonly ok: true;
    readonly data: T;
} | {
    readonly ok: false;
    readonly rejected: IntentRejected;
};

interface FormStateRestore {
    readonly _tag: 'FormStateRestore';
    readonly state: FormControlValue;
    readonly mode: 'restore' | 'autocomplete';
}

type FormValue = FormDataEntryValue | readonly FormDataEntryValue[];

type FormValues<Schema extends StandardSchemaV1> = In<Schema> extends Readonly<Record<string, unknown>> ? {
    readonly [K in keyof In<Schema> & string]?: string | readonly string[];
} : FormFields;

interface GyralElement<S, M extends Tagged> extends HTMLElement {
    /** Current model state. */
    readonly state: S;
    /** Feeds a message through `update`, as if an intent had produced it. */
    send(msg: M): void;
    /** Per-instance driver substitutions by name (test fakes). Checked before the spec's. */
    drivers: DriverOverrides;
    /**
     * Per-instance store instances by store name (tests, islands). Checked before the nearest
     * `<gyral-stores>` provider and the document default (ADR 0013).
     */
    stores: StoreOverrides;
    /**
     * Messages applied through `update` right after `init`, before the first render. The server
     * uses it to render a rejected form with the same reducer as the JS path (ADR 0008). Ignored
     * when the element resumes from a hydration seed (the seed already contains their effect).
     */
    initialMessages: readonly Tagged[];
}

interface GyralElementClass<S, M extends Tagged, P, O extends Tagged = never, N extends string = string> {
    /** Instances expose their declared props as settable properties. */
    new (): GyralElement<S, M> & {
        -readonly [K in keyof P]: P[K];
    };
    readonly spec: ComponentSpec<S, M, P, N>;
    readonly tagName: string;
    /** Native custom-element registration flag, true when the spec opts into forms. */
    readonly formAssociated?: boolean;
    /** Type-only: the outputs this component emits (read by `child()`). */
    readonly outputs?: O;
    /** Type-only: the component's intent names, the keys of `intent` (read by `intentsOf()`). */
    readonly intentNames?: N;
}

interface Head {
    readonly title: string;
    readonly description?: string;
    /** Absolute URL, usually `new URL(match.path, origin).href` (ADR 0009 "Canonical paths"). */
    readonly canonical?: string;
    /** `<meta name="robots">`, e.g. `'noindex, follow'`. */
    readonly robots?: string;
    /** Later entries win over earlier ones with the same name or property. */
    readonly meta?: readonly HeadMeta[];
    /** Later entries win over earlier ones with the same attributes other than `href`. */
    readonly links?: readonly HeadLink[];
    /** Structured data, each written as one `<script type="application/ld+json">`. */
    readonly jsonLd?: readonly JsonValue[];
    /** `<html lang>`. */
    readonly lang?: string;
    /** `<html dir>`. */
    readonly dir?: 'ltr' | 'rtl' | 'auto';
}

interface HeadLink {
    readonly rel: string;
    readonly href: string;
    readonly [attribute: string]: string;
}

type HeadMeta = {
    readonly name: string;
    readonly content: string;
    readonly media?: string;
} | {
    readonly property: string;
    readonly content: string;
    readonly media?: string;
};

type HookAttributes = Readonly<Record<string, string | true>>;

interface HookResult<A extends readonly unknown[] = readonly unknown[]> {
    readonly [HOOK]: HookSpec<A>;
    readonly [COMMIT_HOOK]: (part: HookPart, result: HookResult) => void;
    readonly args: A;
}

interface HookSpec<A extends readonly unknown[]> {
    /** Attributes for the server-rendered start tag. */
    server?(args: A): HookAttributes;
    /** Runs after the commit when `args` changed; `prev` is undefined the first time. */
    client(el: Element, args: A, prev: A | undefined): void;
    /**
     * When `client` runs again: `'args'` (the default) when an argument changed (`Object.is`),
     * `'always'` on every render that commits the hook's position (a skipped `each` row doesn't).
     */
    readonly update?: 'args' | 'always';
    /**
     * Teardown, with the last arguments `client` got: runs
     * when Gyral removes the element, when the position stops holding this hook, or when the host
     * disconnects (not on moves). After a host reconnects, `client` runs again with `prev`
     * undefined.
     */
    dispose?(el: Element, args: A): void;
}

interface Hydrated {
    readonly _tag: 'Hydrated';
    /** `true` when the instance resumed from server-rendered markup (a hydration seed). */
    readonly serverRendered: boolean;
}

type HydrateStrategy = 'load' | 'idle' | 'visible' | 'interaction';

interface IntentInput {
    /** The intent's name (a message tag): the `data-intent-<event>` or `data-intent` value. */
    readonly name: string;
    readonly event: Event;
    /** The element carrying the intent attribute (`event.currentTarget` is Gyral's root). */
    readonly target: Element;
    /** `value` of the input, select, textarea or button that carries the intent. */
    readonly value: string | undefined;
    /** `checked` for checkbox and radio inputs. */
    readonly checked: boolean | undefined;
    /** Submitted data (including the submitter button) when the intent is on a `<form>`. */
    readonly formData: FormData | undefined;
    /**
     * `detail` of any `CustomEvent`: a Gyral child's output, or the event of another custom
     * element (a map's `marker-select`). Unknown until the parser checks it (a guard, a schema).
     */
    readonly detail: unknown;
    /** `KeyboardEvent.key` for `keydown`/`keyup` intents. */
    readonly key: string | undefined;
    /** For `toggle` intents (popover, `<details>`): the state it changed to. */
    readonly newState: 'open' | 'closed' | undefined;
    /** For `command` intents: the invoker's command (e.g. `--clear`) and source. */
    readonly command: CommandInfo | undefined;
}

type IntentNames<N extends string> = {
    readonly [K in N]: K;
};

type IntentParser<M, P = unknown, S = unknown> = (input: IntentInput, ctx: ParserCtx<P, S>) => ParseResult<M> | Promise<ParseResult<M>>;

interface IntentRejected {
    readonly _tag: 'IntentRejected';
    /** The `data-intent` name whose input was rejected. */
    readonly intent: string;
    readonly issues: readonly FieldIssue[];
    /**
     * For `form()` rejections: what the user submitted, so the view can re-fill the form. On
     * the no-JS path (ADR 0008 server half) the server re-renders the page from this.
     */
    readonly values?: FormFields | undefined;
}

type Intents<M extends Tagged, P = unknown, N extends string = string, S = unknown> = {
    readonly [K in N]: ParserFor<M, P, K, S>;
};

type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
    readonly [key: string]: JsonValue;
};

interface ListResult {
    readonly [EACH]: (part: ChildPart, list: ListResult) => void;
    readonly items: readonly unknown[];
    readonly key: (item: unknown) => unknown;
    readonly row: (item: unknown, picked: unknown) => unknown;
    readonly pick: ((item: unknown) => unknown) | undefined;
}

type Next<S, M> = S | readonly [S, ReadonlyArray<Command<M | IntentRejected>>];

type OutputEvent<O extends Tagged = Tagged> = CustomEvent<O>;

type OutputsOf<C> = C extends {
    readonly outputs?: infer O;
} ? Exclude<O, undefined> : never;

interface OutputSource<O extends Tagged, E extends Element> {
    new (): E;
    /** Type-only marker for the component's output union. Never set at runtime. */
    readonly outputs?: O;
}

interface ParserCtx<P, S = unknown> extends Ctx<P> {
    /** The state when the event fires. */
    readonly state: Readonly<S>;
}

type ParseResult<M> = M | IntentRejected | undefined;

type ParserFor<M extends Tagged, P, K, S = unknown> = string extends K ? // The wide form (any intent name), which every specific spec is assignable to.
IntentParser<M, P, S> | true | TrueOnlyForFieldlessMessage : K extends M['_tag'] ? IntentParser<Variant<M, K>, P, S> | TagOnly<Variant<M, K>> : IntentParser<M, P, S>;

interface Prop<T> {
    readonly kind: PropKind;
    /** The attribute name, `false` for property only, `undefined` for the kebab-case default. */
    readonly attribute: string | false | undefined;
    /**
     * Refines (string/number/boolean) or defines (json/value) the accepted values: a Standard
     * Schema, or for json/value a type guard (props.ts `checkValue` tells them apart).
     */
    readonly schema: StandardSchemaV1 | PropGuard<unknown> | undefined;
    /** A missing value is a bug: warned once per instance at first render. */
    readonly required: boolean;
    /** Used whenever the element's value is missing (`boolean` props default to `false`). */
    readonly default?: unknown;
    /**
     * When a new value counts as unchanged (no re-render, no `PropsChanged`): `Object.is`, the
     * same JSON for `prop.json`, or the `equals` option of `prop.json`/`prop.value`.
     */
    readonly equals: (a: unknown, b: unknown) => boolean;
    /** Type-only: the value components see. Never set. */
    readonly [OUTPUT]?: () => T;
}

type PropDeclarations<P> = {
    readonly [K in keyof P]-?: Prop<P[K]>;
};

type PropGuard<T> = (value: unknown) => value is T;

type PropKind = 'string' | 'number' | 'boolean' | 'json' | 'value';

interface PropsChanged<P> {
    readonly _tag: 'PropsChanged';
    readonly props: P;
    readonly prev: P;
}

type PropsOf<T extends Readonly<Record<string, Prop<unknown>>>> = {
    readonly [K in keyof T]: T[K] extends Prop<infer V> ? V : never;
};

interface RawResult {
    readonly [MARKUP]: (part: ChildPart, html: string) => void;
    readonly html: string;
}

type Reducer<S, M, Msg, P = object> = (state: S, msg: Msg, ctx: Ctx<P>) => Next<S, M>;

const add: Reducer<State, Msg, Variant<Msg, 'Add'>, object> = (s, m) => …

interface RetryPolicy<E = unknown> {
    /** Retries after the first failure. */
    readonly times: number;
    /** Delay before each retry (the base delay for exponential backoff). Default 0. */
    readonly delayMs?: number;
    readonly backoff?: 'fixed' | 'exponential';
    /** Full jitter: wait a random time between 0 and the computed delay, so clients spread out. */
    readonly jitter?: boolean;
    /**
     * Which failures to retry, given the driver's typed error (its `toError`, else the thrown
     * value). Default: every failure. For `@gyral/http`, `retryableHttpError`.
     */
    readonly retryIf?: (error: E) => boolean;
}

type SeedCheck<S> = {
    readonly ok: true;
    readonly state: S;
} | {
    readonly ok: false;
    readonly issues: readonly string[];
};

type ShadowOption = boolean | {
    readonly delegatesFocus?: boolean;
};

interface StandardSchemaV1<Input = unknown, Output = Input> {
    /** The Standard Schema properties. */
    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
}

type Stateless = Readonly<Record<string, never>>;

interface Store<S, M extends Tagged> extends StoreRef<S> {
    readonly spec: StoreSpec<S, M>;
    /**
     * A fresh, independent instance. `initial` skips `init`'s state (a server seed, a test
     * fixture); `init`'s commands still run on the client.
     */
    instance(initial?: S): StoreInstance<S, M>;
    /** Checks a seed with `spec.schema` (ok as-is without one). */
    checkSeed(seed: unknown): SeedCheck<S>;
    /** Type-only marker for the message type. Never set at runtime. */
    readonly messageType?: (msg: M) => M;
}

interface StoreChanged {
    readonly _tag: 'StoreChanged';
    /** The store's name. Narrow with `changed(store, msg)`. */
    readonly store: string;
    readonly state: unknown;
    readonly prev: unknown;
}

interface StoreInstance<S, M extends Tagged> {
    readonly store: Store<S, M>;
    readonly state: S;
    /** Feeds a message through the store's `update` and notifies subscribers on change. */
    send(msg: M): void;
    /** Called after every state change. Returns an unsubscribe function. */
    subscribe(listener: (state: S, prev: S) => void): () => void;
    /** Per-instance driver substitutions (test fakes). Checked before the spec's. */
    drivers: DriverOverrides;
    /** Stops running commands and drops subscribers. */
    dispose(): void;
    /** Set by the registry that holds the instance (store-to-store `send`). */
    bindScope(resolve: StoreResolver): void;
}

type StoreOverrides = Readonly<Record<string, AnyStoreInstance>>;

type StoreReader = <S>(store: StoreRef<S>) => S;

interface StoreRef<S> {
    readonly name: string;
    /** Type-only marker for the state type. Never set at runtime. */
    readonly stateType?: (state: S) => S;
}

type StoreResolver = (store: AnyStore) => AnyStoreInstance;

interface StoreSpec<S, M extends Tagged> {
    /** Initial state (and optional commands, e.g. load a saved cart). */
    readonly init: () => Next<S, M>;
    readonly update: StoreUpdate<S, M>;
    /** Driver substitutions by name for this store's commands. */
    readonly drivers?: DriverOverrides;
    /**
     * Validates the server's page seed before the client uses it (any synchronous Standard
     * Schema). An invalid seed is reported with console.error and the store starts from `init`.
     */
    readonly schema?: StandardSchemaV1<unknown, S>;
}

type StoreUpdate<S, M extends Tagged> = {
    readonly [K in M['_tag']]: (state: S, msg: Variant<M, K>) => Next<S, M>;
};

type Styles = StyleSource | string | readonly Styles[];

interface StyleSource {
    readonly [STYLE]: true;
    readonly text: string;
}

interface SubscriptionContext<I> {
    /** The command's input (a room code, a URL, a store key). */
    readonly input: I;
    /** Aborts when the command is switched away or its component disconnects. */
    readonly signal: AbortSignal;
    /**
     * Ends the subscription with an error: the source is released and the command's
     * `onFailure` gets it. Wrap the driver in `retry()` to subscribe again instead.
     */
    readonly fail: (error: unknown) => void;
}

interface SubscriptionOptions<E> {
    readonly concurrency?: Concurrency;
    readonly toError?: (cause: unknown) => E;
}

interface Tagged {
    readonly _tag: string;
}

interface TemplateResult {
    readonly [SOURCE]: readonly string[] | TemplateObject;
    readonly values: readonly unknown[];
}

type Unsubscribe = (() => void) | {
    readonly unsubscribe: () => void;
};

type Update<S, M extends Tagged, P = object> = {
    readonly [K in M['_tag']]: Reducer<S, M, Variant<M, K>, P>;
} & {
    readonly PropsChanged?: Reducer<S, M, PropsChanged<P>, P>;
    readonly IntentRejected?: Reducer<S, M, IntentRejected, P>;
    readonly StoreChanged?: Reducer<S, M, StoreChanged, P>;
    readonly Hydrated?: Reducer<S, M, Hydrated, P>;
    readonly Errored?: Reducer<S, M, Errored, P>;
    readonly FormReset?: Reducer<S, M, FormReset, P>;
    readonly FormDisabled?: Reducer<S, M, FormDisabled, P>;
    readonly FormStateRestore?: Reducer<S, M, FormStateRestore, P>;
};

type Variant<M extends Tagged, K> = Extract<M, {
    readonly _tag: K;
}>;

function makeLocalStorageDriver<T>(schema: StandardSchemaV1<unknown, T>, options?: LocalStorageOptions<T>): Driver<StorageInput<T>, StorageOutput<T>, StorageError>;

interface LocalStorageOptions<T> {
    /** Name for normal driver substitution. Default localStorage. */
    readonly name?: string;
    /** Keys and Clear are restricted to this namespace. Default empty (all keys). */
    readonly prefix?: string;
    /** Accessed only when a command runs. Default native localStorage. */
    readonly storage?: () => Storage;
    /** A transformed schema may need to encode model values back into its input shape. */
    readonly encode?: (value: T) => unknown;
}

type StorageChangeSource = 'initial' | 'driver' | 'tab';

interface StorageDecodeError {
    readonly _tag: 'StorageDecodeError';
    readonly key: string;
    readonly issues: readonly StandardSchemaV1.Issue[];
}

type StorageError = StorageDecodeError | {
    readonly _tag: 'StorageAccessError';
    readonly operation: StorageInput<unknown>['_tag'];
    readonly key: string | undefined;
    readonly message: string;
};

type StorageInput<T> = {
    readonly _tag: 'Read';
    readonly key: string;
} | {
    readonly _tag: 'Write';
    readonly key: string;
    readonly value: T;
} | {
    readonly _tag: 'Remove';
    readonly key: string;
} | {
    readonly _tag: 'Clear';
} | {
    readonly _tag: 'Watch';
    readonly key: string;
};

type StorageOutput<T> = {
    readonly _tag: 'StorageValue';
    readonly key: string;
    readonly entry: StoredValue<T>;
} | {
    readonly _tag: 'StorageWritten' | 'StorageRemoved';
    readonly key: string;
} | {
    readonly _tag: 'StorageCleared';
} | {
    readonly _tag: 'StorageChanged';
    readonly key: string;
    readonly source: StorageChangeSource;
    readonly entry: StoredValue<T>;
} | {
    readonly _tag: 'StorageDecodeFailed';
    readonly key: string;
    readonly source: StorageChangeSource;
    readonly error: StorageDecodeError;
};

type StoredValue<T> = {
    readonly found: false;
} | {
    readonly found: true;
    readonly value: T;
};

function makeIndexedDBDriver<S extends IndexedDBStores>(stores: S, options: IndexedDBOptions<S>): Driver<IndexedDBInput<S>, IndexedDBOutput<S>, IndexedDBError>;

type IndexedDBError = {
    readonly _tag: 'IndexedDBBlockedError';
    readonly database: string;
    readonly version: number;
} | {
    readonly _tag: 'IndexedDBInputError';
    readonly message: string;
} | {
    readonly _tag: 'IndexedDBAccessError';
    readonly database: string;
    readonly phase: 'encode' | 'open' | 'upgrade' | 'transaction';
    readonly name: string;
    readonly message: string;
} | {
    readonly _tag: 'IndexedDBDecodeError';
    readonly store: string;
    readonly issues: readonly StandardSchemaV1.Issue[];
    /** Native transaction completed before decoding. Its writes cannot be undone. */
    readonly committed: true;
};

type IndexedDBInput<S extends IndexedDBStores> = IndexedDBOperation<S> | {
    readonly _tag: 'Transaction';
    readonly operations: readonly IndexedDBOperation<S>[];
};

type IndexedDBOperation<S extends IndexedDBStores> = {
    [K in keyof S & string]: {
        readonly _tag: 'Read' | 'Delete';
        readonly store: K;
        readonly key: IDBValidKey;
    } | {
        readonly _tag: 'Put';
        readonly store: K;
        readonly value: IndexedDBRecord<S[K]>;
        readonly key?: IDBValidKey;
    } | {
        readonly _tag: 'Query';
        readonly store: K;
        readonly index?: string;
        readonly range?: IndexedDBRange;
        readonly direction?: IDBCursorDirection;
        readonly limit: number;
    };
}[keyof S & string];

interface IndexedDBOptions<S extends IndexedDBStores> {
    readonly database: string;
    readonly version: number;
    readonly name?: string;
    readonly factory?: () => IDBFactory;
    /** Synchronous: queue migration requests before returning; never await. */
    readonly upgrade?: (db: IDBDatabase, oldVersion: number, newVersion: number, transaction: IDBTransaction) => void;
    readonly encode?: <K extends keyof S & string>(store: K, value: IndexedDBRecord<S[K]>) => unknown;
}

type IndexedDBOutput<S extends IndexedDBStores> = IndexedDBResult<S> | {
    readonly _tag: 'Committed';
    readonly results: readonly IndexedDBResult<S>[];
};

type IndexedDBRange = {
    readonly _tag: 'Only';
    readonly key: IDBValidKey;
} | {
    readonly _tag: 'Lower' | 'Upper';
    readonly key: IDBValidKey;
    readonly open?: boolean;
} | {
    readonly _tag: 'Bound';
    readonly lower: IDBValidKey;
    readonly upper: IDBValidKey;
    readonly lowerOpen?: boolean;
    readonly upperOpen?: boolean;
};

type IndexedDBRecord<S extends StandardSchemaV1> = StandardSchemaV1.InferOutput<S>;

type IndexedDBResult<S extends IndexedDBStores> = {
    [K in keyof S & string]: {
        readonly _tag: 'Record';
        readonly store: K;
        readonly key: IDBValidKey;
        readonly entry: {
            readonly found: false;
        } | {
            readonly found: true;
            readonly value: IndexedDBRecord<S[K]>;
        };
    } | {
        readonly _tag: 'Put' | 'Deleted';
        readonly store: K;
        readonly key: IDBValidKey;
    } | {
        readonly _tag: 'Records';
        readonly store: K;
        readonly records: readonly {
            readonly key: IDBValidKey;
            readonly value: IndexedDBRecord<S[K]>;
        }[];
    };
}[keyof S & string];

type IndexedDBStores = Readonly<Record<string, StandardSchemaV1>>;

function gyralVitePreset(options?: GyralViteOptions): GyralViteConfig;

export default defineConfig({ ...gyralVitePreset(), build: { … } });

interface ComponentsOptions {
    /** Directories (relative to Vite's root) whose modules' `define()` tags are found. Default `['src']`. */
    readonly include?: readonly string[];
    /**
     * Tag → module (relative to Vite's root) for components the scan can't find: those defined
     * through a wrapper such as `defineMemberForm({ tag: 'member-form' })`, which calls
     * `define()` itself. Listed entries win over scanned ones.
     */
    readonly modules?: Readonly<Record<string, string>>;
}

interface ElementTypesOptions {
    /** Source directories to scan, relative to the Vite root. Default `['src']`. */
    readonly dirs?: readonly string[];
    /** The declaration file to write, relative to the Vite root. Default `.gyral/elements.d.ts`. */
    readonly out?: string;
}

interface GyralViteConfig {
    readonly plugins: Plugin[];
    readonly optimizeDeps: {
        readonly include: string[];
    };
}

interface GyralViteOptions {
    /**
     * Generated element typings (`.gyral/elements.d.ts`, see `ElementTypesOptions`), or `false`
     * to write none. Default: on, scanning `src`.
     */
    readonly types?: ElementTypesOptions | false;
    /** Modules to pre-bundle in dev, so Vite doesn't discover them mid-run and reload. */
    readonly optimize?: readonly string[];
    /** Template compiler options (`vite build` only). */
    readonly compiler?: TemplateCompilerOptions;
    /**
     * The app is never server-rendered: leave the hydration code out of the browser bundle.
     * Default false.
     */
    readonly clientOnly?: boolean;
    /**
     * Automatic component loading (ADR 0016 addendum): every component defined under `include`
     * gets a client module the build splits out, and a loader (`virtual:gyral/components`, added
     * to the client build's input) imports a tag's module once that tag is in the page.
     * `renderPage({ components })` then links exactly the components a page rendered, so pages
     * need no client entry of their own and no side-effect imports. Default off.
     */
    readonly components?: boolean | ComponentsOptions;
}

interface TemplateCompilerOptions {
    /**
     * Module specifiers whose `html` (and `svg`) exports are the view layer's tags (default
     * `DEFAULT_TEMPLATE_SOURCES`). An import matches when its specifier is listed, or when it
     * resolves to the same module as a listed one; core's own view modules always match. A
     * source other than '@gyral/core' must also export `compiled` (and `compiledSvg` when it
     * exports `svg`).
     */
    readonly sources?: readonly string[];
    /**
     * Rule 7's extra check with parse5 (an optional peer dependency): `true` (default) uses
     * 'parse5' when it is installed, a string names the module to load, `false` skips it.
     */
    readonly parse5?: boolean | string;
}