sygnal 5.3.6 → 5.4.0

package/dist/index.d.ts

@@ -1,25 +1,370 @@
-import type { MainDOMSource } from './cycle/dom/MainDOMSource'
-import type { EnrichedEventStream } from './cycle/dom/enrichEventStream'
-import type { StateSource } from './cycle/state/index'
-import xsDefault from 'xstream'
-import type { MemoryStream, Stream } from 'xstream'
+import xsDefault, { Stream, MemoryStream } from 'xstream';
+export { MemoryStream, Stream } from 'xstream';
+import { VNode, VNodeData } from 'snabbdom/build/vnode.js';
+export { VNode, VNodeData } from 'snabbdom/build/vnode.js';
+export { default as debounce } from 'xstream/extra/debounce.js';
+export { default as throttle } from 'xstream/extra/throttle.js';
+export { default as delay } from 'xstream/extra/delay.js';
+export { default as dropRepeats } from 'xstream/extra/dropRepeats.js';
+export { default as sampleCombine } from 'xstream/extra/sampleCombine.js';
+export { default as flattenConcurrently } from 'xstream/extra/flattenConcurrently.js';
+export { default as flattenSequentially } from 'xstream/extra/flattenSequentially.js';
+export { default as concat } from 'xstream/extra/concat.js';
+export { h } from 'snabbdom/build/h.js';
+import { Options } from 'snabbdom/build/init.js';
+import { Module } from 'snabbdom/build/modules/module.js';
+
+type Predicate = (ev: Event) => boolean;
+type Comparator = Record<string, unknown>;
+type PreventDefaultOpt = boolean | Predicate | Comparator;
+
+interface EnrichedEventStream<T = Event> extends Stream<T> {
+    value(): EnrichedEventStream<string>;
+    value<R>(fn: (val: string) => R): EnrichedEventStream<R>;
+    checked(): EnrichedEventStream<boolean>;
+    checked<R>(fn: (val: boolean) => R): EnrichedEventStream<R>;
+    data(name: string): EnrichedEventStream<string | undefined>;
+    data<R>(name: string, fn: (val: string | undefined) => R): EnrichedEventStream<R>;
+    target(): EnrichedEventStream<EventTarget | null>;
+    target<R>(fn: (el: EventTarget | null) => R): EnrichedEventStream<R>;
+    key(): EnrichedEventStream<string>;
+    key<R>(fn: (key: string) => R): EnrichedEventStream<R>;
+}
+
+declare class DocumentDOMSource {
+    private _name;
+    private _selector;
+    constructor(_name: string, selector?: string);
+    select(selector: string): DocumentDOMSource;
+    elements(): MemoryStream<Array<Document | Element>>;
+    element(): MemoryStream<Document | Element | null>;
+    events<K extends keyof DocumentEventMap>(eventType: K, options?: EventsFnOptions, bubbles?: boolean): EnrichedEventStream<DocumentEventMap[K]>;
+}
+
+declare class BodyDOMSource {
+    private _name;
+    constructor(_name: string);
+    select(selector: string): BodyDOMSource;
+    elements(): MemoryStream<Array<HTMLBodyElement>>;
+    element(): MemoryStream<HTMLBodyElement>;
+    events<K extends keyof HTMLBodyElementEventMap>(eventType: K, options?: EventsFnOptions, bubbles?: boolean): Stream<HTMLBodyElementEventMap[K]>;
+}
+
+interface EventsFnOptions {
+    useCapture?: boolean;
+    passive?: boolean;
+    bubbles?: boolean;
+    preventDefault?: PreventDefaultOpt;
+}
+type DOMSource = MainDOMSource | DocumentDOMSource | BodyDOMSource;
+
+interface Scope$1 {
+    type: 'sibling' | 'total' | 'selector';
+    scope: string;
+}
+type IsolateSink<T extends VNode> = (s: Stream<T>, scope: string) => Stream<T>;
+
+interface CycleDOMEvent extends Event {
+    propagationHasBeenStopped: boolean;
+    ownerTarget: Element;
+}
+declare class EventDelegator {
+    private rootElement$;
+    isolateModule: IsolateModule;
+    private virtualListeners;
+    private origin;
+    private domListeners;
+    private nonBubblingListeners;
+    private domListenersToAdd;
+    private nonBubblingListenersToAdd;
+    private virtualNonBubblingListener;
+    constructor(rootElement$: Stream<Element>, isolateModule: IsolateModule);
+    addEventListener(eventType: string, namespace: Array<Scope$1>, options: EventsFnOptions, bubbles?: boolean): Stream<Event>;
+    removeElement(element: Element, namespace?: Array<Scope$1>): void;
+    private insertListener;
+    private getVirtualListeners;
+    private setupDOMListener;
+    private setupNonBubblingListener;
+    private resetEventListeners;
+    private putNonBubblingListener;
+    private onEvent;
+    private bubble;
+    private doBubbleStep;
+    private patchEvent;
+    private mutateEventCurrentTarget;
+}
+
+declare class IsolateModule {
+    private namespaceTree;
+    private namespaceByElement;
+    private eventDelegator;
+    private vnodesBeingRemoved;
+    constructor();
+    setEventDelegator(del: EventDelegator): void;
+    private insertElement;
+    private removeElement;
+    getElement(namespace: Array<Scope$1>, max?: number): Element | undefined;
+    getRootElement(elm: Element): Element | undefined;
+    getNamespace(elm: Element): Array<Scope$1> | undefined;
+    createModule(): {
+        create(emptyVNode: VNode, vNode: VNode): void;
+        update(oldVNode: VNode, vNode: VNode): void;
+        destroy(vNode: VNode): void;
+        remove(vNode: VNode, cb: Function): void;
+        post(): void;
+    };
+}
+
+interface SpecialSelector {
+    body: BodyDOMSource;
+    document: DocumentDOMSource;
+}
+declare class MainDOMSource {
+    private _rootElement$;
+    private _sanitation$;
+    private _namespace;
+    _isolateModule: IsolateModule;
+    private _eventDelegator;
+    private _name;
+    constructor(_rootElement$: Stream<Element>, _sanitation$: Stream<null>, _namespace: Array<Scope$1>, _isolateModule: IsolateModule, _eventDelegator: EventDelegator, _name: string);
+    private _elements;
+    elements(): MemoryStream<Array<Element>>;
+    element(): MemoryStream<Element>;
+    get namespace(): Array<Scope$1>;
+    select<T extends keyof SpecialSelector>(selector: T): SpecialSelector[T];
+    select(selector: string): MainDOMSource;
+    events<K extends keyof HTMLElementEventMap>(eventType: K, options?: EventsFnOptions, bubbles?: boolean): EnrichedEventStream<HTMLElementEventMap[K]>;
+    dispose(): void;
+    isolateSource: (source: MainDOMSource, scope: string) => MainDOMSource;
+    isolateSink: IsolateSink<VNode>;
+}
+
+type Reducer$1<T> = (state: T | undefined) => T | undefined;
+type Getter<T, R> = (state: T | undefined) => R | undefined;
+type Setter<T, R> = (state: T | undefined, childState: R | undefined) => T | undefined;
+type Lens$1<T, R> = {
+    get: Getter<T, R>;
+    set: Setter<T, R>;
+};
+type Scope<T, R> = string | number | Lens$1<T, R>;
+
+declare function isolateSource<T, R>(source: StateSource<T>, scope: Scope<T, R>): StateSource<R>;
+declare function isolateSink<T, R>(innerReducer$: Stream<Reducer$1<R>>, scope: Scope<T, R>): Stream<Reducer$1<T>>;
+/**
+ * Represents a piece of application state dynamically changing over time.
+ */
+declare class StateSource<S> {
+    stream: MemoryStream<S>;
+    private _stream;
+    private _name;
+    constructor(stream: Stream<S>, name: string);
+    /**
+     * Selects a part (or scope) of the state object and returns a new StateSource
+     * dynamically representing that selected part of the state.
+     */
+    select<R>(scope: Scope<S, R>): StateSource<R>;
+    isolateSource: typeof isolateSource;
+    isolateSink: typeof isolateSink;
+}
+
+/**
+ * Types for the 'sygnal/diagnostics' entry (runtime consistency checks).
+ *
+ *   import 'sygnal/diagnostics'   // registers all checks (side effect)
+ *
+ * Checks only run while diagnostics are on: run(App, drivers, { diagnostics: 'warn' }),
+ * or globalThis.__SYGNAL_DEV__ (set by the Vite plugin in dev).
+ */
+
+type DiagnosticSeverity$1 = 'error' | 'warn' | 'info'
+
+// ---------------------------------------------------------------------------
+// inspect (PLAN-1 workstream 2B): a machine-readable app graph. The same shape
+// is produced at runtime (inspect(), getDevTools().inspect(), renderComponent's
+// t.inspect()) and statically (`sygnal-check --graph --json`); JSON Schema:
+// sygnal-check/schema/inspect.schema.json. Fields one side cannot know are
+// null (or omitted).
+// ---------------------------------------------------------------------------
+
+/** How an action is dispatched. */
+type InspectActionTrigger = 'intent' | 'next' | 'builtin' | 'unknown'
+
+interface InspectAction {
+  name: string
+  /**
+   * 'intent': returned by the component's intent. 'builtin': BOOTSTRAP,
+   * INITIALIZE, HYDRATE, DISPOSE or READY. 'next': dispatched with next()
+   * (statically: a next('NAME') literal; at runtime: a model-only action whose
+   * STATE reducer was seen running). 'unknown': none of these is known.
+   */
+  trigger: InspectActionTrigger
+  /** sinks of the model entry (STATE, EVENTS, EFFECT, PARENT, custom drivers); [] without a model entry */
+  sinks: string[]
+}
+
+interface InspectChild {
+  name: string
+  via: 'tag' | 'collection' | 'switchable' | 'slot'
+  /** Collection: the `from` state field, when known */
+  from?: string | null
+  /** runtime: number of live instances behind this entry (e.g. Collection items) */
+  count?: number
+}
+
+interface InspectSelector {
+  /** CSS selector passed to DOM.select() (chained selects joined with a space) */
+  selector: string
+  /** event types listened to; null when unknown (runtime, real DOM) */
+  events: string[] | null
+  /**
+   * whether it matches an element the component itself renders; null when unknown.
+   * static: the class/id is in the view source. renderComponent: an element of the latest
+   * render matches (a conditionally rendered element that is hidden right now gives false).
+   * real DOM: true once a DOM check saw it match, false after SYG103/SYG104, else null.
+   */
+  matched: boolean | null
+  /** the child component whose (isolated) elements it matches instead, if any */
+  isolationHit: string | null
+}
+
+interface InspectDiagnostic {
+  code: string
+  severity: DiagnosticSeverity$1
+  component?: string
+  message: string
+  fix?: string
+  docsUrl?: string
+  data?: any
+  /** static only */
+  file?: string
+  line?: number
+  column?: number
+}
+
+interface InspectComponent {
+  name: string
+  /** runtime: instance number (as a string); static: 'file:line' of the definition */
+  id: string
+  /** runtime: the parent instance's id; static: null (see the parents' `children`) */
+  parentId: string | null
+  /** static only: source file, relative to the working directory */
+  file?: string
+  /**
+   * runtime: how the instance was created; static: 'root' when no scanned
+   * component renders it, else how it is first rendered
+   */
+  kind: 'root' | 'child' | 'collection-item' | 'switchable'
+  actions: InspectAction[]
+  /** state keys (runtime: current state; static: initialState) */
+  stateKeys: string[]
+  /** calculated field names */
+  calculated: string[]
+  /** context fields this component provides (Component.context) */
+  contextProvides: string[]
+  /** context fields its view reads (static only; null at runtime) */
+  contextConsumes?: string[] | null
+  /** EVENTS types this component emits */
+  eventsEmitted: string[]
+  /** EVENTS types this component selects ('*' = EVENTS.select() without a type) */
+  eventsSelected: string[]
+  children: InspectChild[]
+  selectors: InspectSelector[]
+  diagnostics: InspectDiagnostic[]
+}
 
-export declare const ABORT: unique symbol
-export type ABORT = typeof ABORT
+interface InspectGraph {
+  version: 1
+  /** which implementation produced the graph */
+  source?: 'runtime' | 'static'
+  components: InspectComponent[]
+  /** EVENTS bus: type -> names of the components that emit / select it */
+  events: Record<string, { emitters: string[]; selectors: string[] }>
+  /** diagnostics not tied to a listed component */
+  diagnostics: InspectDiagnostic[]
+}
 
-export type DriverSpec<SOURCE = any, SINK = any> = {
+interface ThunkData extends VNodeData {
+    fn(): VNode;
+    args: Array<any>;
+}
+interface Thunk extends VNode {
+    data: ThunkData;
+}
+declare function thunk(sel: string, fn: Function, args: Array<any>): Thunk;
+declare function thunk(sel: string, key: any, fn: Function, args: Array<any>): Thunk;
+
+type FantasyObserver<T> = {
+    next(x: T): void;
+    error(err: any): void;
+    complete(c?: any): void;
+};
+type FantasySubscription = {
+    unsubscribe(): void;
+};
+type FantasyObservable<T> = {
+    subscribe(observer: FantasyObserver<T>): FantasySubscription;
+};
+type Driver<Si, So> = Si extends void ? (() => So) : ((stream: Si) => So);
+
+interface DOMDriverOptions {
+    modules?: Array<Partial<Module>>;
+    reportSnabbdomError?(err: unknown): void;
+    snabbdomOptions?: Options;
+}
+declare function makeDOMDriver(container: string | Element | DocumentFragment, options?: DOMDriverOptions): Driver<Stream<VNode>, MainDOMSource>;
+
+/**
+ * Optional simulated-event hub (used by renderComponent's simulateEvent): a
+ * stream of `{type, event, match(path)}`; each source's events(type) also emits
+ * the hub events whose `match` accepts its selector path (isolation scopes
+ * included as '.___scope' segments).
+ */
+type MockEventHub = Stream<{
+    type: string;
+    event: any;
+    match: (path: string[]) => boolean;
+}>;
+/**
+ * Optional listener callback (renderComponent): called with `live` undefined when events() is
+ * called (SYG103/104 checks), then with true / false when that hub listener is subscribed /
+ * unsubscribed (simulateEvent waits for a just-mounted child's listeners, G-039).
+ */
+type MockOnEvents = (path: string[], eventType: string, live?: boolean) => void;
+type MockConfig = {
+    [name: string]: FantasyObservable<any> | MockConfig;
+};
+declare class MockedDOMSource {
+    private _mockConfig;
+    private _hub?;
+    _path: string[];
+    private _onEvents?;
+    private _elements;
+    constructor(_mockConfig: MockConfig, _hub?: MockEventHub | undefined, _path?: string[], _onEvents?: MockOnEvents | undefined);
+    elements(): any;
+    element(): any;
+    events(eventType: string, options?: EventsFnOptions, bubbles?: boolean): any;
+    select(selector: string): MockedDOMSource;
+    isolateSource(source: MockedDOMSource, scope: string): MockedDOMSource;
+    isolateSink(sink: any, scope: string): any;
+}
+declare function mockDOMSource(mockConfig: MockConfig, hub?: MockEventHub, onEvents?: MockOnEvents): MockedDOMSource;
+
+declare const ABORT: unique symbol
+type ABORT = typeof ABORT
+
+type DriverSpec<SOURCE = any, SINK = any> = {
   source: SOURCE;
   sink: SINK;
 }
 
-export type DriverSpecs = Record<string, DriverSpec<any, any>>
+type DriverSpecs = Record<string, DriverSpec<any, any>>
 
-export type CycleDriver<SINK = any, SOURCE = any> =
+type CycleDriver<SINK = any, SOURCE = any> =
   SINK extends void
     ? (() => SOURCE)
     : ((sink$: Stream<SINK>) => SOURCE)
 
-export type DriverFactories<DRIVERS extends DriverSpecs = DriverSpecs> = {
+type DriverFactories<DRIVERS extends DriverSpecs = DriverSpecs> = {
   [DRIVER_KEY in keyof DRIVERS]: CycleDriver<DRIVERS[DRIVER_KEY]['sink'], DRIVERS[DRIVER_KEY]['source']>
 }
 
@@ -51,23 +396,89 @@ type Reducer<STATE, PROPS, ACTIONS = any, DATA = any, RETURN = any, CONTEXT = {}
   props: ReducerExtras<PROPS, CONTEXT>
 ) => RETURN | ABORT | undefined
 
-export type ExactShape<EXPECTED, ACTUAL extends EXPECTED> = ACTUAL &
+type ExactShape<EXPECTED, ACTUAL extends EXPECTED> = ACTUAL &
   Record<Exclude<keyof ACTUAL, keyof EXPECTED>, never>
 
 type StateOnlyReducer<STATE, RETURN = any> = (
   state: STATE
 ) => RETURN | ABORT
 
-export type Event<DATA = any> = { type: string; data: DATA }
+type Event$1<DATA = any> = { type: string; data: DATA }
+
+// ── EVENTS registry ────────────────────────────────────────────────
+
+/**
+ * Registry of global EVENTS bus event names and their payload types.
+ *
+ * Empty by default, which keeps the EVENTS bus untyped (`any`). Augment it to
+ * type-check `EVENTS.select()`, `event()`, `emit()` and raw EVENTS sink returns:
+ *
+ *   declare module 'sygnal' {
+ *     interface SygnalEvents {
+ *       DELETE_LANE: { laneId: string }
+ *       RESET: void            // no payload: event('RESET')
+ *     }
+ *   }
+ *
+ * Once the registry has at least one entry, unregistered event names are type errors.
+ * The augmenting file must be a module (have at least one import or export).
+ */
+interface SygnalEvents {}
+
+/** Valid event names: `string` while the registry is empty, otherwise the registered names. */
+type EventName = keyof SygnalEvents extends never ? string : keyof SygnalEvents & string
+
+/** Payload type of a registered event (`any` while the registry is empty). */
+type EventPayload<TYPE extends string = string> = keyof SygnalEvents extends never
+  ? any
+  : TYPE extends keyof SygnalEvents ? SygnalEvents[TYPE] : never
+
+/**
+ * An event object as put on the EVENTS bus. While the registry is empty this is `Event<any>`;
+ * otherwise it is the union of `{ type, data }` for every registered event.
+ */
+type RegisteredEvent = keyof SygnalEvents extends never
+  ? Event$1<any>
+  : { [TYPE in keyof SygnalEvents & string]: { type: TYPE; data: SygnalEvents[TYPE] } }[keyof SygnalEvents & string]
 
-export type NonStateSinkReturns = {
+/** The `{ type, data }` object produced by `event(type, ...)` / `emit(type, ...)`. */
+type EmittedEvent<TYPE extends string = string> = keyof SygnalEvents extends never
+  ? { type: TYPE; data: any }
+  : { type: TYPE; data: EventPayload<TYPE> }
+
+/** The `next()` function as seen by an event payload function. */
+type EventNextFunction = (action: string, data?: any, delay?: number) => void
+
+/** Payload function for `event()` / `emit()`: receives the reducer arguments, returns the event data. */
+type EventPayloadFunction<TYPE extends string = string, STATE = any, DATA = any> =
+  (state: STATE, data: DATA, next: EventNextFunction, props: any) => EventPayload<TYPE>
+
+/**
+ * Remaining arguments of `event()` / `emit()` when the payload is a static value.
+ * The payload may be omitted when the registry is empty or the event's payload
+ * type accepts `undefined` (e.g. `void`).
+ */
+type StaticEventArgs<TYPE extends string> = keyof SygnalEvents extends never
+  ? [payload?: any]
+  : undefined extends EventPayload<TYPE>
+    ? [payload?: EventPayload<TYPE>]
+    : [payload: EventPayload<TYPE>]
+
+/**
+ * The sink function returned by `event()`. Use it as the value of an `EVENTS` key in a
+ * model entry: `ACTION: { STATE: ..., EVENTS: event('TYPE', fn) }`.
+ */
+type EventSink<TYPE extends string = string, STATE = any, DATA = any> =
+  (state: STATE, data: DATA, next: any, props: any) => EmittedEvent<TYPE>
+
+type NonStateSinkReturns = {
   EVENTS?: unknown;
   LOG?: unknown;
   PARENT?: unknown;
 }
 
 type ResolvedNonStateSinkReturns<SINK_RETURNS extends NonStateSinkReturns = {}> = {
-  EVENTS: SINK_RETURNS extends { EVENTS: infer EVENTS_RETURN } ? EVENTS_RETURN : Event<any>;
+  EVENTS: SINK_RETURNS extends { EVENTS: infer EVENTS_RETURN } ? EVENTS_RETURN : RegisteredEvent;
   LOG: SINK_RETURNS extends { LOG: infer LOG_RETURN } ? LOG_RETURN : any;
   PARENT: SINK_RETURNS extends { PARENT: infer PARENT_RETURN } ? PARENT_RETURN : any;
 }
@@ -149,20 +560,58 @@ type ComponentModel<STATE, PROPS, DRIVERS, ACTIONS, CALCULATED, SINK_RETURNS ext
       >
     }
 
+type TrimSpaces<S extends string> =
+  S extends ` ${infer REST}` ? TrimSpaces<REST>
+  : S extends `${infer REST} ` ? TrimSpaces<REST>
+  : S
+
+/** Value type produced by a PARENT sink value (a reducer's return, minus ABORT/undefined). */
+type ParentSinkValueReturn<VALUE> =
+  VALUE extends (...args: any[]) => infer RETURN ? Exclude<RETURN, ABORT | undefined | void> : never
+
+type ParentPayloadFromEntry<ENTRY> =
+  ENTRY extends (...args: any[]) => any ? never
+  : ENTRY extends object
+    ? 'PARENT' extends keyof ENTRY ? ParentSinkValueReturn<NonNullable<ENTRY['PARENT']>> : never
+    : never
+
+type ParentPayloadsOfModel<MODEL> = {
+  [ACTION_KEY in keyof MODEL]-?: ACTION_KEY extends `${string}|${infer SINK}`
+    ? TrimSpaces<SINK> extends 'PARENT' ? ParentSinkValueReturn<NonNullable<MODEL[ACTION_KEY]>> : never
+    : ParentPayloadFromEntry<NonNullable<MODEL[ACTION_KEY]>>
+}[keyof MODEL]
+
+type AnyIfNever<T> = [T] extends [never] ? any : T
+
+/**
+ * The value type a component sends to its parent through the `PARENT` sink, inferred from the
+ * component's `model` (object-form `{ PARENT: fn }` entries and `'ACTION | PARENT'` shorthand).
+ * Falls back to `any` when it can't be inferred (no model, a `Component<...>` annotation without
+ * a `PARENT` entry in its `SINK_RETURNS`, or `PARENT: true` pass-through entries only).
+ */
+type ParentPayloadOf<COMPONENT> =
+  COMPONENT extends { model?: infer MODEL }
+    ? 0 extends (1 & MODEL) ? any : AnyIfNever<ParentPayloadsOfModel<NonNullable<MODEL>>>
+    : any
+
 type ChildSource = {
+  /** Typed: the stream type is inferred from the child's PARENT sink (falls back to `any`). */
+  select<COMPONENT extends (...args: any[]) => any>(component: COMPONENT): Stream<ParentPayloadOf<COMPONENT>>;
   select<T = any>(component: (...args: any[]) => any): Stream<T>;
   select<T = any>(name: string): Stream<T>;
 }
 
-export type SygnalDOMSource = MainDOMSource & {
+type SygnalDOMSource = MainDOMSource & {
   [eventName: string]: (selector: string) => EnrichedEventStream<globalThis.Event>
 }
 
-export type EventsSource<EVENTS = any> = Stream<Event<EVENTS>> & {
-  select<T = any>(type: string): Stream<T>;
-}
+type EventsSelect = keyof SygnalEvents extends never
+  ? { select<T = any>(type: string): Stream<T>; }
+  : { select<TYPE extends keyof SygnalEvents & string>(type: TYPE): Stream<SygnalEvents[TYPE]>; }
 
-export type DefaultDrivers<STATE, EVENTS = any> = {
+type EventsSource<EVENTS = any> = Stream<Event$1<EVENTS>> & EventsSelect
+
+type DefaultDrivers<STATE, EVENTS = any> = {
   STATE: {
     source: StateSource<STATE>;
     sink: STATE;
@@ -204,7 +653,7 @@ type IntentActions<ACTIONS> = keyof ACTIONS extends never
  * Supports both `type` aliases and `interface` declarations (interfaces lack implicit index
  * signatures, so a structural fallback check is needed).
  */
-export type FixDrivers<DRIVERS> =
+type FixDrivers<DRIVERS> =
   0 extends (1 & DRIVERS)
     ? {}
     : DRIVERS extends DriverSpecs
@@ -217,6 +666,42 @@ export type FixDrivers<DRIVERS> =
 
 type CombinedSources<STATE, DRIVERS> = Sources<DefaultDrivers<STATE> & DRIVERS> & { dispose$: Stream<boolean> }
 
+/**
+ * The sources object an intent function receives (DOM, STATE, EVENTS, CHILD, dispose$, plus
+ * any custom drivers). Use it to annotate an intent declared before its component:
+ *
+ *   const intent = ({ DOM }: IntentSources<State>) => ({ INC: DOM.click('.inc') })
+ */
+type IntentSources<STATE = any, DRIVERS = {}> = CombinedSources<STATE, FixDrivers<DRIVERS>>
+
+type StreamPayload<STREAM> = STREAM extends Stream<infer T> ? T : any
+
+type IntentReturnToActions<RETURN> = {
+  [ACTION_KEY in keyof RETURN & string]-?: StreamPayload<Exclude<RETURN[ACTION_KEY], undefined>>
+}
+
+/**
+ * Derives the ACTIONS map (action name → payload type) from an intent function's type
+ * (or from its return object type): each key's `Stream<T>` becomes `T`.
+ *
+ *   const intent = ({ DOM }: IntentSources<State>) => ({
+ *     INC:  DOM.click('.inc').mapTo(1),          // Stream<number>
+ *     NAME: DOM.input('.name').value(),         // Stream<string>
+ *   })
+ *   const Counter: Component<State, {}, {}, ActionsOf<typeof intent>> = ...
+ *   Counter.intent = intent
+ *   Counter.model  = { INC: (state, n) => ..., NAME: (state, name) => ... }  // n: number, name: string
+ *
+ * With it, model keys not returned by the intent are type errors (the built-ins BOOTSTRAP,
+ * INITIALIZE, HYDRATE and DISPOSE stay allowed). Actions reached only through `next()` are
+ * added explicitly:
+ *
+ *   type Actions = ActionsOf<typeof intent> & { SAVED: { id: string } }
+ */
+type ActionsOf<INTENT> = INTENT extends (...args: any[]) => infer RETURN
+  ? IntentReturnToActions<RETURN>
+  : IntentReturnToActions<INTENT>
+
 interface ComponentIntent<STATE, DRIVERS, ACTIONS> {
   (args: CombinedSources<STATE, DRIVERS>): Partial<IntentActions<ACTIONS>>
 }
@@ -233,25 +718,25 @@ type Context<STATE, CONTEXT> = keyof CONTEXT extends never
   ? { [field: string]: boolean | StateOnlyReducer<STATE, any> }
   : { [CONTEXT_KEY in keyof CONTEXT]: boolean | StateOnlyReducer<STATE, CONTEXT[CONTEXT_KEY]> }
 
-export type Lense<PARENT_STATE = any, CHILD_STATE = any> = {
+type Lense<PARENT_STATE = any, CHILD_STATE = any> = {
   get: (state: PARENT_STATE) => CHILD_STATE;
   set: (state: PARENT_STATE, childState: CHILD_STATE) => PARENT_STATE;
 }
 
-export type Lens<PARENT_STATE = any, CHILD_STATE = any> = Lense<PARENT_STATE, CHILD_STATE>
+type Lens<PARENT_STATE = any, CHILD_STATE = any> = Lense<PARENT_STATE, CHILD_STATE>
 
-export type Filter<ITEM = any> = (item: ITEM) => boolean
+type Filter<ITEM = any> = (item: ITEM) => boolean
 
-export type SortFunction<ITEM = any> = (a: ITEM, b: ITEM) => number
+type SortFunction<ITEM = any> = (a: ITEM, b: ITEM) => number
 
-export type SortObject<ITEM = any> = {
+type SortObject<ITEM = any> = {
   [field: string]: 'asc' | 'desc' | SortFunction<ITEM>
 }
 
 /**
  * Sygnal Component
  */
-export type Component<
+type Component<
   STATE = any,
   PROPS = { [prop: string]: any },
   DRIVERS = {},
@@ -267,6 +752,12 @@ export type Component<
   model?: ComponentModel<STATE, PROPS, FixDrivers<DRIVERS>, ACTIONS, CALCULATED, SINK_RETURNS, CONTEXT>;
   intent?: ComponentIntent<STATE & CALCULATED, FixDrivers<DRIVERS>, ACTIONS>;
   initialState?: STATE;
+  /**
+   * Give a sub-component its own state instead of the slice its parent passes in.
+   * Required to use `initialState` on a sub-component (otherwise SYG405). Without a
+   * `state` prop the state is local to the instance and never written to the parent.
+   */
+  isolatedState?: boolean;
   calculated?: Calculated<STATE, CALCULATED>;
   storeCalculatedInState?: boolean;
   context?: Context<STATE & CALCULATED, CONTEXT>;
@@ -279,7 +770,7 @@ export type Component<
 /**
  * Sygnal Root Component
  */
-export type RootComponent<
+type RootComponent<
   STATE = any,
   DRIVERS = {},
   ACTIONS = {},
@@ -294,68 +785,175 @@ export type RootComponent<
  */
 type AnyComponent = ((...args: any[]) => any) & Record<string, any>
 
-export type CollectionProps<PROPS = any> = {
+/** Keys of STATE whose value is an array (optional/nullable arrays included). */
+type ArrayKeysOf<STATE> = {
+  [KEY in keyof STATE]-?: NonNullable<STATE[KEY]> extends ReadonlyArray<any> ? KEY : never
+}[keyof STATE] & string
+
+/**
+ * Valid `from` values for a Collection: any string or Lense while the parent STATE is unknown
+ * (`any`); otherwise an array-valued key of STATE or a Lense over STATE.
+ */
+type CollectionFrom<STATE = any> = 0 extends (1 & STATE)
+  ? string | Lense
+  : ArrayKeysOf<STATE> | Lense<STATE, any>
+
+/**
+ * Collection props. Pass the parent component's state type as STATE to type-check `from`:
+ *
+ *   const TaskCollection = Collection<{}, LaneState>   // instantiation expression
+ *   <TaskCollection of={TaskCard} from="tasks" />       // 'tasks' must be an array key of LaneState
+ */
+type CollectionProps<PROPS = any, STATE = any> = {
   of: AnyComponent;
-  from: string | Lense;
+  from: CollectionFrom<STATE>;
   filter?: Filter;
   sort?: string | SortFunction | SortObject;
-} & Omit<PROPS, 'of' | 'from' | 'filter' | 'sort'>
+  /**
+   * Item field used as the key that tracks each item (its component instance, isolation
+   * scope and DOM) across updates. Items are keyed by `id` by default; keys should be
+   * unique and stable (an item without the field is keyed by its index).
+   */
+  idfield?: string;
+} & Omit<PROPS, 'of' | 'from' | 'filter' | 'sort' | 'idfield'>
 
-export type SwitchableProps<PROPS = any> = {
+type SwitchableProps<PROPS = any> = {
   of: Record<string, AnyComponent>;
   current: string;
   state?: string | Lense;
 } & Omit<PROPS, 'of' | 'state' | 'current'>
 
-export type PortalProps = {
+type PortalProps = {
   target: string;
   children?: any;
 }
 
-export type TransitionProps = {
+type TransitionProps = {
   name?: string;
   duration?: number;
   appear?: boolean;
   children?: any;
 }
 
-export type SlotProps = {
+type SuspenseProps = {
+  /**
+   * Shown (wrapped in `<div data-sygnal-suspense="pending">`) while any child is not ready:
+   * a `lazy()` component still loading, or a component with an explicit READY model entry
+   * that hasn't emitted true. A string renders as text. Without it the children render as-is.
+   */
+  fallback?: JSX.Element | string;
+  children?: any;
+}
+
+type SlotProps = {
   name?: string;
   children?: any;
 }
 
-export type ClassesType = (string | string[] | { [className: string]: boolean | undefined })[]
+type ClassesType = (string | string[] | { [className: string]: boolean | undefined })[]
+
+/**
+ * Diagnostics mode.
+ * - 'off'     — no checks, no collection (default in production)
+ * - 'collect' — collect diagnostics silently (read with getDiagnostics())
+ * - 'warn'    — collect and print warn/error diagnostics to the console (default in Vite dev)
+ * - 'error'   — collect and throw on warn/error diagnostics
+ */
+type DiagnosticsMode = 'off' | 'collect' | 'warn' | 'error'
+
+/** Stable diagnostic code, e.g. 'SYG101'. See https://sygnal.js.org/reference/errors */
+type DiagnosticCode = `SYG${number}`
+
+type DiagnosticSeverity = 'error' | 'warn' | 'info'
+
+type Diagnostic = {
+  code: DiagnosticCode;
+  severity: DiagnosticSeverity;
+  /** Name of the component the diagnostic is about */
+  component?: string;
+  /** What is wrong */
+  message: string;
+  /** How to fix it */
+  fix?: string;
+  /** Structured payload (check-specific) */
+  data?: any;
+  /** Link to the docs entry for this code */
+  docsUrl: string;
+  /** Fully formatted message: `[Sygnal SYG123] Component: message. fix docsUrl` */
+  text: string;
+  timestamp: number;
+}
+
+type DiagnosticsOptions = {
+  mode?: DiagnosticsMode;
+  /** Codes to ignore entirely */
+  ignore?: DiagnosticCode[];
+}
 
-export type RunOptions = {
+type RunOptions = {
   mountPoint?: string;
   fragments?: boolean;
   useDefaultDrivers?: boolean;
+  /**
+   * Runtime diagnostics. Takes precedence over `globalThis.__SYGNAL_DEV__`
+   * (set by the Sygnal Vite plugin in dev), which enables 'warn'. Default: 'off'.
+   */
+  diagnostics?: DiagnosticsMode | DiagnosticsOptions;
 }
 
-export type SygnalSinks<STATE = any, DRIVERS = {}> = {
+/** All diagnostics collected so far (most recent last). */
+declare function getDiagnostics(): Diagnostic[]
+
+/** Clear the collected diagnostics. */
+declare function clearDiagnostics(): void
+
+/** Subscribe to diagnostics as they are reported. Returns an unsubscribe function. */
+declare function onDiagnostic(callback: (diagnostic: Diagnostic) => void): () => void
+
+
+/**
+ * The Sygnal DevTools bridge (also `window.__SYGNAL_DEVTOOLS__` once run() has
+ * initialized it in a browser). Only the stable, documented members are typed.
+ */
+interface SygnalDevTools {
+  /** true while the browser extension is connected */
+  readonly connected: boolean
+  /** Diagnostics collected so far (same as getDiagnostics()) */
+  getDiagnostics(): Diagnostic[]
+  /**
+   * The machine-readable app graph of the live components. Present only when the
+   * 'sygnal/diagnostics' dev entry is loaded (it attaches this method); needs diagnostics on.
+   */
+  inspect?(): InspectGraph
+}
+
+/** The DevTools bridge singleton. */
+declare function getDevTools(): SygnalDevTools | undefined
+
+type SygnalSinks<STATE = any, DRIVERS = {}> = {
   [SINK_NAME in keyof (DefaultDrivers<STATE> & FixDrivers<DRIVERS>) | string]?: Stream<any>
 }
 
-export type AnyComponentModule<COMPONENT = any> =
+type AnyComponentModule<COMPONENT = any> =
   | COMPONENT
   | { default: COMPONENT }
   | Array<COMPONENT | { default: COMPONENT } | null | undefined>
   | null
   | undefined
 
-export type SygnalApp<STATE = any, DRIVERS = {}> = {
+type SygnalApp<STATE = any, DRIVERS = {}> = {
   sources: CombinedSources<STATE, FixDrivers<DRIVERS>>;
   sinks: SygnalSinks<STATE, DRIVERS>;
   dispose: () => void;
   hmr: (newComponent?: AnyComponentModule<RootComponent<STATE, DRIVERS>>, state?: STATE) => void;
 }
 
-export type HotModuleAPI = {
+type HotModuleAPI = {
   accept: (...args: any[]) => any;
   dispose?: (callback: () => void) => void;
 }
 
-export function run<
+declare function run<
   STATE = any,
   DRIVERS = {},
   ACTIONS = {},
@@ -367,21 +965,21 @@ export function run<
   options?: RunOptions
 ): SygnalApp<STATE & CALCULATED, FixDrivers<DRIVERS>>
 
-export function run(
+declare function run(
   component: any,
   drivers?: Record<string, CycleDriver<any, any>>,
   options?: RunOptions
 ): SygnalApp<any, {}>
 
-export function enableHMR<STATE = any, DRIVERS = {}>(
+declare function enableHMR<STATE = any, DRIVERS = {}>(
   app: SygnalApp<STATE, DRIVERS>,
   hot: HotModuleAPI,
   loadComponent?: () => Promise<AnyComponentModule<RootComponent<STATE, DRIVERS>>> | AnyComponentModule<RootComponent<STATE, DRIVERS>>,
   acceptDependencies?: string | string[]
 ): SygnalApp<STATE, DRIVERS>
 
-export function classes(...classes: ClassesType): string
-export function exactState<STATE>(): <ACTUAL extends STATE>(state: ExactShape<STATE, ACTUAL>) => STATE
+declare function classes(...classes: ClassesType): string
+declare function exactState<STATE>(): <ACTUAL extends STATE>(state: ExactShape<STATE, ACTUAL>) => STATE
 
 // ── Reducer helpers ────────────────────────────────────────────────
 
@@ -395,7 +993,7 @@ export function exactState<STATE>(): <ACTUAL extends STATE>(state: ExactShape<ST
  * returns the partial update to merge:
  *   `set((state, title) => ({ title }))`
  */
-export function set<S = any>(
+declare function set<S = any>(
   partial: Partial<S> | ((state: S, data: any, next: Function, props: any) => Partial<S>)
 ): (state: S, data: any, next: Function, props: any) => S
 
@@ -404,33 +1002,69 @@ export function set<S = any>(
  *
  *   `toggle('showModal')`
  */
-export function toggle<S = any>(field: keyof S & string): (state: S) => S
+declare function toggle<S = any>(field: keyof S & string): (state: S) => S
+
+type EmitEntry<TYPE extends string> = keyof SygnalEvents extends never
+  ? { EVENTS: (state: any, actionData: any, next: Function, props: any) => { type: string; data: any } }
+  : { EVENTS: (state: any, actionData: any, next: Function, props: any) => EmittedEvent<TYPE> }
 
 /**
  * Create a model entry that emits an EVENTS bus event.
+ * Prefer `event()` inside the object form: `ACTION: { EVENTS: event('TYPE', fn) }`.
  *
  *   `emit('DELETE_LANE', (state) => ({ laneId: state.id }))`
  *   `emit('REFRESH')`
+ *
+ * With a `SygnalEvents` registry, `type` and the payload are checked against it.
+ */
+declare function emit<TYPE extends EventName>(
+  type: TYPE,
+  data: (state: any, actionData: any, next: Function, props: any) => EventPayload<TYPE>
+): EmitEntry<TYPE>
+declare function emit<TYPE extends EventName>(
+  type: TYPE,
+  ...data: StaticEventArgs<TYPE>
+): EmitEntry<TYPE>
+
+/**
+ * Create an EVENTS sink function that puts `{ type, data }` on the EVENTS bus.
+ * Use it as the `EVENTS` value inside an object-form model entry:
+ *
+ *   DELETE: {
+ *     STATE:  (state) => ({ ...state, deleting: true }),
+ *     EVENTS: event('DELETE_LANE', (state) => ({ laneId: state.id })),
+ *   }
+ *
+ * The payload is either a function `(state, data, next, props) => payload` or a static value:
+ *   `event('RESET')`, `event('SET_MODE', 'dark')`.
+ *
+ * With a `SygnalEvents` registry, `type` must be a registered name and the payload must match
+ * its type. When used inside a model, the payload function's `state` and `data` parameters are
+ * typed from the component.
  */
-export function emit(
-  type: string,
-  data?: any | ((state: any, actionData: any, next: Function, props: any) => any)
-): { EVENTS: (state: any, actionData: any, next: Function, props: any) => { type: string; data: any } }
+declare function event<TYPE extends EventName, STATE = any, DATA = any>(
+  type: TYPE,
+  payload: EventPayloadFunction<TYPE, STATE, DATA>
+): EventSink<TYPE, STATE, DATA>
+declare function event<TYPE extends EventName>(
+  type: TYPE,
+  ...payload: StaticEventArgs<TYPE>
+): EventSink<TYPE>
 
 /**
  * Any object with an events() method (e.g., DOM.select('form')).
  * Uses permissive signature to be compatible with MainDOMSource's overloaded events().
  */
-export type FormSource = {
+type FormSource = {
   events(eventName: string, ...args: any[]): Stream<any>
 }
 
-export type FormData<FIELDS extends Record<string, string> = Record<string, string>> = FIELDS & {
+type FormData<FIELDS extends Record<string, string> = Record<string, string>> = FIELDS & {
   event: globalThis.Event;
   eventType: string;
 }
 
-export type ProcessFormOptions = {
+type ProcessFormOptions = {
   events?: string | string[];
   preventDefault?: boolean;
 }
@@ -449,7 +1083,7 @@ export type ProcessFormOptions = {
  * // form$ is Stream<FormData<{ username: string; email: string }>>
  * // form$.username is typed as string ✓
  */
-export function processForm<FIELDS extends Record<string, string> = Record<string, string>>(
+declare function processForm<FIELDS extends Record<string, string> = Record<string, string>>(
   target: FormSource,
   options?: ProcessFormOptions
 ): Stream<FormData<FIELDS>>
@@ -458,11 +1092,11 @@ export function processForm<FIELDS extends Record<string, string> = Record<strin
  * Any object with an events() method (e.g., DOM.select('.draggable')).
  * Uses permissive signature to be compatible with MainDOMSource's overloaded events().
  */
-export type DragSource = {
+type DragSource = {
   events(eventName: string, ...args: any[]): Stream<any>
 }
 
-export function processDrag(
+declare function processDrag(
   sources?: { draggable?: DragSource; dropZone?: DragSource },
   options?: { effectAllowed?: string }
 ): {
@@ -472,7 +1106,7 @@ export function processDrag(
   drop$: Stream<DragEvent>
 }
 
-export type DragDriverRegistration = {
+type DragDriverRegistration = {
   category:   string;
   draggable?: string;
   dropZone?:  string;
@@ -482,24 +1116,24 @@ export type DragDriverRegistration = {
   dragImage?: string;
 }
 
-export type DragStartPayload = {
+type DragStartPayload = {
   element: HTMLElement;
   dataset: Record<string, string>;
 }
 
-export type DropPayload = {
+type DropPayload = {
   dropZone:     HTMLElement;
   insertBefore: HTMLElement | null;
 }
 
-export type DragDriverCategory = {
+type DragDriverCategory = {
   events(eventType: 'dragstart'): Stream<DragStartPayload>;
   events(eventType: 'dragend'):   Stream<null>;
   events(eventType: 'drop'):      Stream<DropPayload>;
   events(eventType: string):      Stream<any>;
 }
 
-export type DragDriverSource = {
+type DragDriverSource = {
   select(category: string): DragDriverCategory;
   dragstart(category: string): Stream<DragStartPayload>;
   dragend(category: string): Stream<null>;
@@ -508,9 +1142,9 @@ export type DragDriverSource = {
   dispose(): void;
 }
 
-export function makeDragDriver(): (sink$: Stream<DragDriverRegistration | DragDriverRegistration[]>) => DragDriverSource
+declare function makeDragDriver(): (sink$: Stream<DragDriverRegistration | DragDriverRegistration[]>) => DragDriverSource
 
-export type ComponentFactoryOptions<
+type ComponentFactoryOptions<
   STATE = any,
   PROPS = any,
   DRIVERS = {},
@@ -536,7 +1170,7 @@ export type ComponentFactoryOptions<
   debug?: boolean;
 }
 
-export function component<
+declare function component<
   STATE = any,
   PROPS = any,
   DRIVERS = {},
@@ -548,25 +1182,50 @@ export function component<
   options: ComponentFactoryOptions<STATE, PROPS, DRIVERS, ACTIONS, CALCULATED, CONTEXT, SINK_RETURNS>
 ): Component<STATE, PROPS, DRIVERS, ACTIONS, CALCULATED, CONTEXT, SINK_RETURNS>
 
-export function collection(...args: any[]): any
-export function switchable(...args: any[]): any
-export function portal(...args: any[]): any
+declare function collection(...args: any[]): any
+declare function switchable(...args: any[]): any
+declare function portal(...args: any[]): any
 
-export function Collection<PROPS extends { [prop: string]: any }>(props: CollectionProps<PROPS>): JSX.Element
-export function Switchable<PROPS extends { [prop: string]: any }>(props: SwitchableProps<PROPS>): JSX.Element
-export function Portal(props: PortalProps): JSX.Element
-export function Transition(props: TransitionProps): JSX.Element
-export function Slot(props: SlotProps): JSX.Element
+declare function Collection<PROPS extends { [prop: string]: any }, STATE = any>(props: CollectionProps<PROPS, STATE>): JSX.Element
+declare function Switchable<PROPS extends { [prop: string]: any }>(props: SwitchableProps<PROPS>): JSX.Element
+declare function Portal(props: PortalProps): JSX.Element
+declare function Transition(props: TransitionProps): JSX.Element
+declare function Suspense(props: SuspenseProps): JSX.Element
+declare function Slot(props: SlotProps): JSX.Element
+
+/**
+ * What `lazy()` returns: a sub-component used in JSX with its own props only
+ * (`<Chart title="Sales" />`; `state` is optional, as for any sub-component), that
+ * still carries the component statics (`model`, `intent`, …) once loaded.
+ */
+type LazyComponent<PROPS = any> = ((
+  props: PROPS & { state?: any; children?: JSX.Element | JSX.Element[] }
+) => JSX.Element) & Omit<Component<any, PROPS>, never>
 
-export function lazy<PROPS = any>(
+declare function lazy<PROPS = any>(
   loadFn: () => Promise<{ default: Component<any, PROPS> } | Component<any, PROPS>>
-): Component<any, PROPS>
+): LazyComponent<PROPS>
+
+/** Payload on `errors()` of a driverFromAsync source when a request fails */
+type AsyncDriverError<INCOMING = any> = {
+  /** The rejection reason (or what `post` threw) */
+  error: any;
+  /** The request that failed */
+  request: INCOMING;
+  /** The request's selector property (default 'category') is copied here */
+  [selectorProperty: string]: any;
+}
 
-export type AsyncDriverFromFunction<INCOMING = any, OUTGOING = any> = {
+type AsyncDriverFromFunction<INCOMING = any, OUTGOING = any> = {
   select: (selector?: string | ((value: OUTGOING) => boolean)) => Stream<OUTGOING>
+  /**
+   * Failed requests (rejected promise, rejected/throwing `post`). Filters like
+   * `select()`. Failures are only console.error'd while nothing listens here.
+   */
+  errors: (selector?: string | ((error: AsyncDriverError<INCOMING>) => boolean)) => Stream<AsyncDriverError<INCOMING>>
 }
 
-export type DriverFromAsyncOptions<INCOMING = any, OUTGOING = any, RETURN = any> = {
+type DriverFromAsyncOptions<INCOMING = any, OUTGOING = any, RETURN = any> = {
   selector?: string;
   args?: string | string[] | ((incoming: INCOMING) => any | any[]);
   return?: string | undefined;
@@ -574,71 +1233,101 @@ export type DriverFromAsyncOptions<INCOMING = any, OUTGOING = any, RETURN = any>
   post?: (value: RETURN, incoming: INCOMING) => OUTGOING | Promise<OUTGOING>;
 }
 
-export function driverFromAsync<INCOMING = any, RETURN = any, OUTGOING = any>(
+declare function driverFromAsync<INCOMING = any, RETURN = any, OUTGOING = any>(
   promiseReturningFunction: (...args: any[]) => Promise<RETURN>,
   options?: DriverFromAsyncOptions<INCOMING, OUTGOING, RETURN>
 ): (fromApp$: Stream<INCOMING>) => AsyncDriverFromFunction<INCOMING, OUTGOING>
 
-export interface Ref<T = HTMLElement> {
+interface Ref<T = HTMLElement> {
   current: T | null;
 }
 
-export interface Ref$<T = HTMLElement> extends Ref<T> {
+interface Ref$<T = HTMLElement> extends Ref<T> {
   stream: MemoryStream<T | null>;
 }
 
-export function createRef<T = HTMLElement>(): Ref<T>
-export function createRef$<T = HTMLElement>(): Ref$<T>
+declare function createRef<T = HTMLElement>(): Ref<T>
+declare function createRef$<T = HTMLElement>(): Ref$<T>
 
-export interface Command {
+interface Command {
   send(type: string, data?: any): void;
 }
 
-export interface CommandSource {
+interface CommandSource {
   select(type: string): Stream<any>;
 }
 
-export function createCommand(): Command
+declare function createCommand(): Command
 
 // ── PWA Helpers ──────────────────────────────────────────────
 
-export interface ServiceWorkerSource {
+interface ServiceWorkerSource {
   select(type?: 'installed' | 'activated' | 'waiting' | 'controlling' | 'error' | 'message' | string): Stream<any>;
 }
 
-export interface ServiceWorkerCommand {
+interface ServiceWorkerCommand {
   action: 'skipWaiting' | 'postMessage' | 'unregister';
   data?: any;
 }
 
-export interface ServiceWorkerOptions {
+interface ServiceWorkerOptions {
   scope?: string;
 }
 
-export function makeServiceWorkerDriver(
+declare function makeServiceWorkerDriver(
   scriptUrl: string,
   options?: ServiceWorkerOptions
 ): (sink$: Stream<ServiceWorkerCommand>) => ServiceWorkerSource
 
-export const onlineStatus$: Stream<boolean>
+declare const onlineStatus$: Stream<boolean>
 
-export interface InstallPrompt {
+interface InstallPrompt {
   select(type: 'beforeinstallprompt' | 'appinstalled'): Stream<any>;
   prompt(): Promise<any> | undefined;
 }
 
-export function createInstallPrompt(): InstallPrompt
+declare function createInstallPrompt(): InstallPrompt
+
+interface SimulatedEventInit {
+  /** Merged into `event.target` (value, checked, dataset, ...) */
+  target?: Record<string, any>;
+  /** Shorthand for target.value */
+  value?: any;
+  /** Shorthand for target.checked */
+  checked?: boolean;
+  /** Merged into target.dataset (values become strings, like the DOM) */
+  dataset?: Record<string, any>;
+  /** Alias for dataset */
+  data?: Record<string, any>;
+  /** Keyboard key (e.key) */
+  key?: string;
+  /**
+   * Don't fail when the selector matches no rendered element: wait up to 300ms for it, then
+   * drop the event with SYG103 (info). Not copied onto the event.
+   */
+  allowMissing?: boolean;
+  /** Any other event properties are copied onto the event */
+  [prop: string]: any;
+}
 
-export interface RenderOptions {
+interface RenderOptions {
   /** Override initial state (defaults to component's .initialState) */
   initialState?: any;
   /** Mock DOM configuration — maps selectors to event streams */
   mockConfig?: Record<string, any>;
-  /** Additional drivers beyond DOM, EVENTS, STATE, and LOG */
+  /** Additional drivers beyond DOM, EVENTS, STATE, and LOG (model sinks without a driver get a no-op one) */
   drivers?: Record<string, any>;
+  /**
+   * Diagnostics mode while rendered. Default: 'collect' (error-severity messages still print),
+   * or the current mode when diagnostics are already on. Restored when the last instance is
+   * disposed. Dev checks require `import 'sygnal/diagnostics'` (the Vite plugin adds it under Vitest).
+   */
+  diagnostics?: DiagnosticsMode;
+  /** Enable strict (canonical-form) runtime checks while rendered (requires 'sygnal/diagnostics') */
+  strict?: boolean;
 }
 
-export interface RenderResult {
+interface RenderResult {
   /** Stream of state values */
   state$: Stream<any>;
   /** Stream of rendered VNode trees */
@@ -649,19 +1338,73 @@ export interface RenderResult {
   sinks: Record<string, any>;
   /** All source objects by driver name */
   sources: Record<string, any>;
-  /** Push an action directly into the intent→model pipeline */
+  /** Push an action into the intent→model pipeline under its real name (all sinks of the entry run) */
   simulateAction: (actionName: string, data?: any) => void;
-  /** Wait for state to satisfy a predicate (resolves with the matching state) */
+  /**
+   * Dispatch a synthetic DOM event through the mock DOM source so the component's real intent
+   * streams fire (DOM.click('.x'), DOM.select('.x').events('click'), .value(), .data()).
+   * Targets the first rendered element matching `selector` and bubbles within its isolation scope.
+   * Selectors match the rendered tree like the real DOM: tag, .class, #id, [attr], [attr="v"]
+   * (^= $= *= ~=), :first-child, :last-child, :only-child, :nth-child(an+b|odd|even),
+   * :nth-last-child(), :first/last/only/nth-of-type, :not(), descendant ' ' and child '>'
+   * combinators, ',' lists. Other syntax (:has(), '+', '~', pseudo-elements...) throws.
+   * If nothing matches yet, the event waits (up to 300ms, re-checked on every render) for a
+   * matching element, then targets the first one. If none renders, the test fails with an
+   * error naming the selector: it rejects the pending next()/waitForState()/settle(), or is
+   * thrown by the next t.* call or dispose() (or by simulateEvent itself when nothing is
+   * pending and the tree is quiet). Pass `{ allowMissing: true }` to drop the event with SYG103
+   * instead. It is never sent to every listener with that selector string. It also waits until
+   * the listeners it reaches are subscribed (a just-mounted child subscribes a few ms late).
+   * `'document'` / `'body'` go to the DOM.select('document' | 'body') listeners.
+   * simulateAction/simulateEvent calls are delivered in call order; a waiting event holds the
+   * calls after it. Reports SYG104 (selector only matches inside a child component).
+   */
+  simulateEvent: (selector: string, eventType: string, eventInit?: SimulatedEventInit) => void;
+  /** Resolves once the component is subscribed (earlier simulate* calls are buffered and replayed) */
+  ready: () => Promise<void>;
+  /**
+   * Wait for a state that satisfies the predicate. Matches the recorded HISTORY too: a state
+   * from before the call resolves it (e.g. `count === 0` right after a reset resolves at once
+   * with the initial state). Resolves with the matching state once the whole tree (children
+   * included) has rendered it. Use `next()` to wait for a new state.
+   */
   waitForState: (predicate: (state: any) => boolean, timeoutMs?: number) => Promise<any>;
+  /**
+   * Wait for the next state emitted AFTER this call that satisfies the predicate (default: any
+   * state). Resolves with it once the whole tree (children included) has rendered it; rejects
+   * after timeoutMs (default 2000).
+   */
+  next: (predicate?: (state: any) => boolean, timeoutMs?: number) => Promise<any>;
+  /**
+   * Resolves once nothing is pending: the component is ready, no simulated input is waiting,
+   * and nothing in the tree has rendered, reduced or changed state for 20ms (longer than
+   * next()'s default delay). Rejects after timeoutMs (default 2000) if it never calms down.
+   */
+  settle: (timeoutMs?: number) => Promise<void>;
   /** Collected state values — grows as new states are emitted */
   states: any[];
-  /** Tear down the component and clean up all listeners */
+  /** Live array of values emitted on a sink (EVENTS as {type, data}, PARENT unwrapped, custom drivers) */
+  sinkValues: (sinkName: string) => any[];
+  /** Live array of EVENTS sink emissions ({type, data}) */
+  emitted: Array<{ type: string; data: any }>;
+  /** Live array of diagnostics reported while rendered */
+  diagnostics: Diagnostic[];
+  /** Throws (with the formatted texts) if any warn/error diagnostics were collected */
+  expectNoDiagnostics: () => void;
+  /** Latest rendered VNode serialized to HTML ('' before the first render) */
+  html: () => string;
+  /** Tear down the component, clean up listeners and restore the diagnostics mode */
   dispose: () => void;
+  /**
+   * The app graph of the rendered tree (components, actions, selectors with the mock DOM's
+   * match / isolation results, EVENTS, diagnostics). Throws unless 'sygnal/diagnostics' is loaded.
+   */
+  inspect: () => InspectGraph;
 }
 
-export function renderComponent(componentDef: any, options?: RenderOptions): RenderResult
+declare function renderComponent(componentDef: any, options?: RenderOptions): RenderResult
 
-export interface RenderToStringOptions {
+interface RenderToStringOptions {
   /** Initial state for the root component */
   state?: any
   /** Props to pass to the root component */
@@ -679,18 +1422,10 @@ export interface RenderToStringOptions {
 /**
  * Render a Sygnal component to an HTML string on the server.
  */
-export function renderToString(componentDef: any, options?: RenderToStringOptions): string
+declare function renderToString(componentDef: any, options?: RenderToStringOptions): string
 
-export const xs: typeof xsDefault
+declare const xs: typeof xsDefault
 
-export { default as debounce } from 'xstream/extra/debounce.js'
-export { default as throttle } from 'xstream/extra/throttle.js'
-export { default as delay } from 'xstream/extra/delay.js'
-export { default as dropRepeats } from 'xstream/extra/dropRepeats.js'
-export { default as sampleCombine } from 'xstream/extra/sampleCombine.js'
-
-export * from './cycle/dom/index'
-export type { MemoryStream, Stream }
 
 /**
  * JSX Types
@@ -717,3 +1452,5 @@ declare global {
     }
   }
 }
+
+export { ABORT, type ActionsOf, type AnyComponentModule, type ArrayKeysOf, type AsyncDriverError, type AsyncDriverFromFunction, type ClassesType, Collection, type CollectionFrom, type CollectionProps, type Command, type CommandSource, type Component, type ComponentFactoryOptions, type CycleDOMEvent, type CycleDriver, type DOMDriverOptions, type DOMSource, type DefaultDrivers, type Diagnostic, type DiagnosticCode, type DiagnosticSeverity, type DiagnosticsMode, type DiagnosticsOptions, type DragDriverCategory, type DragDriverRegistration, type DragDriverSource, type DragSource, type DragStartPayload, type DriverFactories, type DriverFromAsyncOptions, type DriverSpec, type DriverSpecs, type DropPayload, type EmittedEvent, type EnrichedEventStream, type Event$1 as Event, type EventName, type EventPayload, type EventPayloadFunction, type EventSink, type EventsFnOptions, type EventsSource, type ExactShape, type Filter, type FixDrivers, type FormData, type FormSource, type HotModuleAPI, type InspectAction, type InspectActionTrigger, type InspectChild, type InspectComponent, type InspectDiagnostic, type InspectGraph, type InspectSelector, type InstallPrompt, type IntentSources, type LazyComponent, type Lens, type Lense, MainDOMSource, type MockConfig, MockedDOMSource, type NonStateSinkReturns, type ParentPayloadOf, Portal, type PortalProps, type ProcessFormOptions, type Ref, type Ref$, type RegisteredEvent, type RenderOptions, type RenderResult, type RenderToStringOptions, type RootComponent, type RunOptions, type ServiceWorkerCommand, type ServiceWorkerOptions, type ServiceWorkerSource, type SimulatedEventInit, Slot, type SlotProps, type SortFunction, type SortObject, Suspense, type SuspenseProps, Switchable, type SwitchableProps, type SygnalApp, type SygnalDOMSource, type SygnalDevTools, type SygnalEvents, type SygnalSinks, type Thunk, type ThunkData, Transition, type TransitionProps, classes, clearDiagnostics, collection, component, createCommand, createInstallPrompt, createRef, createRef$, driverFromAsync, emit, enableHMR, event, exactState, getDevTools, getDiagnostics, lazy, makeDOMDriver, makeDragDriver, makeServiceWorkerDriver, mockDOMSource, onDiagnostic, onlineStatus$, portal, processDrag, processForm, renderComponent, renderToString, run, set, switchable, thunk, toggle, xs };