sygnal 6.4.0 → 6.6.0

package/dist/index.d.ts

@@ -2041,9 +2041,23 @@ type DiagnosticSeverity$1 = 'error' | 'warn' | 'info'
 
 /** How an action is dispatched. */
 /** 'agent' (static, PLAN-6 K-1): only the component's `agent` declaration dispatches it */
-type InspectActionTrigger = 'intent' | 'next' | 'reply' | 'builtin' | 'agent' | 'unknown'
+/**
+ * 'behavior' (static, PLAN-10 A-8): a `uses` entry's action nothing else triggers that the behavior
+ * may dispatch itself where the checker can't list it (a package behavior, an open model, ...)
+ */
+type InspectActionTrigger = 'intent' | 'next' | 'reply' | 'builtin' | 'agent' | 'behavior' | 'unknown'
+
+/**
+ * PLAN-10 A-4 (static only): a source position, 1-based. `file` (relative to the working
+ * directory) only when it isn't the component's file.
+ */
+interface InspectLocation {
+  line: number
+  column: number
+  file?: string
+}
 
-interface InspectAction {
+interface InspectAction extends Partial<InspectLocation> {
   name: string
   /**
    * 'intent': returned by the component's intent. 'builtin': BOOTSTRAP,
@@ -2057,18 +2071,56 @@ interface InspectAction {
   trigger: InspectActionTrigger
   /** sinks of the model entry (STATE, EVENTS, EFFECT, PARENT, custom drivers); [] without a model entry */
   sinks: string[]
+  /** the `uses` key of the behavior that owns it ('pager' for 'pager.NEXT') */
+  behavior?: string
+  /** static, PLAN-10 A-4: the model entry (line/column on the action: the intent property, else this) */
+  modelAt?: InspectLocation
+  /**
+   * static, PLAN-10 A-7 (actions with a STATE sink only): the top-level state keys the STATE
+   * reducer(s) may write (a behavior's: its slice); [] when it never changes state; null when unknown
+   */
+  writes?: string[] | null
+  /** static, PLAN-10 A-7: a STATE reducer may return undefined (removes a Collection item) */
+  removes?: true
 }
 
-interface InspectChild {
+interface InspectChild extends Partial<InspectLocation> {
   name: string
-  via: 'tag' | 'collection' | 'switchable' | 'slot'
+  /**
+   * 'layout' (static, PLAN-10 A-9): Vike's shell, a +Wrapper / +Layout rendering the next +Layout in
+   * or a +Page it applies to (Wrapper(s) > Layout(s) > Page); no location (no JSX site)
+   */
+  via: 'tag' | 'collection' | 'switchable' | 'slot' | 'layout'
   /** Collection: the `from` state field, when known */
   from?: string | null
   /** runtime: number of live instances behind this entry (e.g. Collection items) */
   count?: number
+  /** runtime, PLAN-10 D522: the ids of those instances */
+  ids?: string[]
+  /**
+   * static, PLAN-10 A-3: the id of the component it renders (resolved through the import); null when
+   * it isn't in the graph (a package, a widget, a file not scanned, a dynamic value)
+   */
+  id?: string | null
+  /** static, PLAN-10 A-1: a literal `state` lens (`<Greeting state="host" />`) */
+  state?: string
+  /** static, PLAN-10 A-2: the package the tag is imported from ('sygnal/ui') */
+  external?: string
+  /** static, PLAN-10 A-2: a widget tag (defineWidget, fromZag, fromReact, the sygnal/ui Zag parts) */
+  widget?: true
+}
+
+/** PLAN-10 A-5 (static): a CHILD.select(Child) call in an intent */
+interface InspectChildSelect extends InspectLocation {
+  /** the selected component's name as written */
+  child: string | null
+  /** its id; null when it isn't in the graph */
+  id: string | null
+  /** the intent actions whose stream contains the call (the receivers of the child's PARENT sink) */
+  actions: string[]
 }
 
-interface InspectSelector {
+interface InspectSelector extends Partial<InspectLocation> {
   /** CSS selector passed to DOM.select() (chained selects joined with a space) */
   selector: string
   /** event types listened to; null when unknown (runtime, real DOM) */
@@ -2084,10 +2136,12 @@ interface InspectSelector {
   isolationHit: string | null
   /** PLAN-4 CT-1: the control this selector is (its key), when it is `[data-control="<Key>"]` */
   control?: string
+  /** the `uses` key of the behavior that listens to it */
+  behavior?: string
 }
 
 /** PLAN-4 CT-1: a control (controls()) a component renders */
-interface InspectControl {
+interface InspectControl extends Partial<InspectLocation> {
   /** the control's key (rendered as data-control="<name>") */
   name: string
   /** the intrinsic tag of a tag spec; null for a spec object */
@@ -2102,10 +2156,14 @@ interface InspectDiagnostic {
   code: string
   severity: DiagnosticSeverity$1
   component?: string
+  /** static, PLAN-10 A-3: the id of the component it is attached to */
+  componentId?: string
   message: string
   fix?: string
   docsUrl?: string
   data?: any
+  /** runtime only: when it was reported (ms since the epoch; each is reported once per process) */
+  timestamp?: number
   /** static only */
   file?: string
   line?: number
@@ -2160,6 +2218,12 @@ interface InspectComponent {
   name: string
   /** runtime: instance number (as a string); static: 'file:line' of the definition */
   id: string
+  /**
+   * static, PLAN-10 D521: 'file#name', stable when lines move (hosts key selection and positions by it);
+   * a second component of the same name in one file gets 'file#name#2', and so on. Runtime (PLAN-10 P-2,
+   * D544): the same key when sygnal/vite's dev server stamped the component function, else absent
+   */
+  key?: 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 */
@@ -2169,6 +2233,32 @@ interface InspectComponent {
    * component renders it, else how it is first rendered
    */
   kind: 'root' | 'child' | 'collection-item' | 'switchable'
+  /** PLAN-10 A-1 / D522: rendered as a component (or started as an entry) but has no statics */
+  viewOnly?: true
+  /**
+   * static, PLAN-10 A-6: started by run(), defineElement() or a Vike +Page / +Layout / +Wrapper; 'unknown' on the
+   * other roots when an entry call's component can't be resolved (picked at run time).
+   * runtime (D522): true on an app's root instance
+   */
+  entry?: true | 'unknown'
+  /**
+   * static, Vike only (PLAN-10 A-9): on a +Page's component its route ('/orders/@id': from the
+   * filesystem, or the literal string a +route file / the config's `route` sets); null for a Route
+   * Function or a route the checker can't read (with `routeDynamic`) and for _error/+Page. On a
+   * +Layout's / +Wrapper's: the URL prefix of the directory it applies to
+   */
+  route?: string | null
+  /**
+   * static, Vike only (PLAN-10 A-9): every route of a component several +Page files export (`route` is
+   * the first, in path order; null for a dynamic one or the error page); omitted otherwise
+   */
+  routes?: (string | null)[]
+  /** static, Vike only (PLAN-10 A-9): the route is a Route Function or can't be read (route: null) */
+  routeDynamic?: true
+  /** runtime, PLAN-10 D522: the app (run()) it belongs to: its root's index among the live roots, oldest first */
+  app?: number
+  /** runtime, PLAN-10 D522: false on a hidden Switchable page and below it; omitted when shown */
+  shown?: false
   actions: InspectAction[]
   /** state keys (runtime: current state; static: initialState) */
   stateKeys: string[]
@@ -2176,14 +2266,27 @@ interface InspectComponent {
   calculated: string[]
   /** context fields this component provides (Component.context) */
   contextProvides: string[]
-  /** context fields its view reads (static only; null at runtime) */
+  /** context fields its view reads (static: the view source; runtime, D530: what its latest render read) */
   contextConsumes?: string[] | null
+  /**
+   * static, PLAN-10 A-7: top-level state keys the view (and its child lenses, calculated and
+   * context functions) reads literally; omitted when none
+   */
+  stateReads?: string[]
+  /** static, PLAN-10 A-7: stateReads may be incomplete (the state used whole somewhere) */
+  stateReadsPartial?: true
   /** EVENTS types this component emits */
   eventsEmitted: string[]
   /** EVENTS types this component selects ('*' = EVENTS.select() without a type) */
   eventsSelected: string[]
   children: InspectChild[]
   selectors: InspectSelector[]
+  /** static, PLAN-10 A-4: where the `context` static's entries are */
+  contextEntries?: Array<InspectLocation & { name: string }>
+  /** static, PLAN-10 A-4: the EVENTS emit and select sites of its intent and model */
+  eventSites?: Array<InspectLocation & { type: string; role: 'emit' | 'select' }>
+  /** static, PLAN-10 A-5: CHILD.select(Child) in its intent */
+  childSelects?: InspectChildSelect[]
   /** PLAN-4 CT-1: the controls it renders (runtime: seen in its renders); omitted when none */
   controls?: InspectControl[]
   /** static only, PLAN-4 GS-2 (G-224): the element commands (ELEMENT sink) its model sends; omitted when none */
@@ -2198,7 +2301,7 @@ interface InspectComponent {
 }
 
 /** PLAN-4 GS-2: an element command a model entry sends (static inspect, sygnal-check --graph) */
-interface InspectCommand {
+interface InspectCommand extends Partial<InspectLocation> {
   /** the model entry that sends it */
   action: string
   /** the command's method (its first key) */
@@ -2220,13 +2323,15 @@ interface InspectAgent {
   description: string | null
   /** the declaration has a read projection */
   read: boolean
-  actions: Array<{ name: string; consequential: boolean; input: boolean }>
+  actions: Array<{ name: string; consequential: boolean; input: boolean } & Partial<InspectLocation>>
+  /** the read-only `agent.queries` tools; omitted when none */
+  queries?: Array<{ name: string; input: boolean } & Partial<InspectLocation>>
   /** spreads: what is listed may be incomplete */
   partial?: true
 }
 
 /** PLAN-4 GS-7: a literal timer spec of a `timers` static (static inspect, sygnal-check --graph) */
-interface InspectTimer {
+interface InspectTimer extends Partial<InspectLocation> {
   name: string
   every?: number | null
   after?: number | null
@@ -2261,8 +2366,12 @@ interface InspectGraph {
   /** 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[] }>
+  /**
+   * EVENTS bus: type -> names of the components that emit / select it (each name once); emitterIds /
+   * selectorIds (PLAN-10 A-3, D522, D528): the id of every such component (static) or instance
+   * (runtime), not parallel to the names
+   */
+  events: Record<string, { emitters: string[]; selectors: string[]; emitterIds?: string[]; selectorIds?: string[] }>
   /** diagnostics not tied to a listed component */
   diagnostics: InspectDiagnostic[]
   /** runtime, PLAN-3 5-3: makeFetchDriver cache entries, by sink name (empty when no cache) */
@@ -2398,7 +2507,9 @@ type ViewProps<STATE = any, PROPS = {}, CONTEXT = {}> =
 
 /**
  * The `state` prop a parent passes to a sub-component in JSX: the name of a field of the
- * parent's state (`state="editor"`) or a lens. Without it the child shares the parent's state.
+ * parent's state (`state="editor"`), a path to nested state (`state="settings.rules"`,
+ * `state="boards[0].title"`; since 6.5.0: a write copies only the levels on the path), or a
+ * lens. Without it the child shares the parent's state.
  */
 type StateProp = string | Lense<any, any>
 
@@ -3913,13 +4024,25 @@ type ArrayKeysOf<STATE> = {
   [KEY in keyof STATE]-?: NonNullable<STATE[KEY]> extends ReadonlyArray<any> ? KEY : never
 }[keyof STATE] & string
 
+/**
+ * Array-valued keys of STATE and dotted paths to arrays in its nested objects, up to three levels
+ * (`'tasks' | 'board.cards'`; since 6.5.0). Paths through array positions (`'boards.0.cards'`)
+ * aren't listed: for a list item, use `byId`.
+ */
+type ArrayPathsOf<STATE, DEPTH extends unknown[] = []> = DEPTH['length'] extends 3 ? never : {
+  [KEY in keyof STATE & string]-?: NonNullable<STATE[KEY]> extends ReadonlyArray<any> ? KEY
+    : NonNullable<STATE[KEY]> extends Record<string, any> ? `${KEY}.${ArrayPathsOf<NonNullable<STATE[KEY]>, [...DEPTH, 1]>}`
+    : 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.
+ * (`any`); otherwise an array-valued key of STATE, a dotted path to one (`'board.cards'`), or a
+ * Lense over STATE.
  */
 type CollectionFrom<STATE = any> = 0 extends (1 & STATE)
   ? string | Lense
-  : ArrayKeysOf<STATE> | Lense<STATE, any>
+  : ArrayPathsOf<STATE> | Lense<STATE, any>
 
 /**
  * Collection props. Pass the parent component's state type as STATE to type-check `from`:
@@ -6084,4 +6207,4 @@ declare global {
  */
 declare function byId<T = any, S = any>(field: string, id: unknown, idKey?: string): { get(state: S): T | undefined; set(state: S, value: T): S }
 
-export { ABORT, type ActionCause, type ActionsOf, type ActiveTimer, type AgentAction, type AgentConfirm, type AgentConfirmInfo, type AgentDeclaration, type AgentIssue, type AgentQuery, type AgentQueryResult, type AgentResult, type AgentSchema, type AgentTool, type AgentToolSet, type AgentToolsOptions, type AguiOptions, type AnswerPick, type AnswerPicks, type AnthropicMessagesOptions, type AnyComponentModule, type AnyControl, type AppErrorHook, type AppErrorInfo, type AppErrorPhase, type ArrayKeysOf, type AsyncDriverError, type AsyncDriverFromFunction, type AsyncRequest, type Behavior, type BehaviorDefinition, type BehaviorFactory, type BehaviorHandler, type BehaviorModelEntry, type BehaviorProps, type BehaviorSources, type BehaviorState, type BehaviorTarget, type BrowserCommand, type BrowserFake, type BrowserFakeOptions, type BrowserIntersection, type BrowserPosition, type BrowserResize, type BrowserSource, type BrowserSources, type BrowserSpec, type Catalog, type CatalogContainer, type CatalogContainerDecl, type CatalogDecl, type CatalogOption, type CatalogParam, type CatalogParamValue, type CatalogParamsOf, type CatalogPart, type CatalogPartDecl, type CatalogRecord, type CatalogTree, type CatalogTreeNode, type ChatAbort, type ChatActions, type ChatAskOptions, type ChatCall, type ChatCard, type ChatCardStatus, type ChatClientTool, type ChatCompletionsOptions, type ChatDelta, type ChatDone, type ChatDriverOptions, type ChatError, type ChatEvent, type ChatOk, type ChatOptions, type ChatOutputOf, type ChatOutputSchema, type ChatRequest, type ChatSource, type ChatState, type ChatStatus, type ChatTool, type ChatToolCall, type ChatToolPart, type ChatTransport, type ChatUsage, type ChromePromptOptions, type ChromePromptStatus, type ChromePromptTransport, type ClassesType, Collection, type CollectionFrom, type CollectionProps, type Command, type CommandBarActions, type CommandBarOptions, type CommandBarResult, type CommandBarState, type CommandBarStatus, type CommandBarUnsure, type CommandSource, type Component, type ComposeActions, type ComposeAnswer, type ComposeBackend, type ComposeNames, type ComposeOptions, type ComposeRenderOptions, type ComposeRenderable, type ComposeState, type ComposeStatus, type ComposeTree, Composed, type ComposedProps, type Connections, type ContainerView, type Control, type ControlCommonProps, type ControlDOMSource, type ControlElementOf, type ControlEvent, type ControlH, type ControlPropsOf, type ControlSpec, type ControlSpecObject, type ControlsOf, type ConvertedSchema, type CycleDOMEvent, type CycleDriver, type DOMDriverOptions, type DOMEventShorthand, type DOMEventShorthands, type DOMSource, type DefaultDrivers, type DefineComponentOptions, type DevToolsActionCause, type DevToolsCopyAsTestOptions, type DevToolsSessionRecording, 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 ElementCommand, type ElementCommandRegistry, type ElementCommands, type ElementProps, type ElementTarget, type EmittedEvent, type EnrichedEventStream, type Event$1 as Event, type EventName, type EventPayload, type EventPayloadFunction, type EventSink, type EventsFnOptions, type EventsSource, type ExactShape, type ExplainedAction, type ExposeWebMcpOptions, type FakeCacheEntry, type FakeChatChunk, type FakeConnection, type FakeConnectionTarget, type FakeReplyOptions, type FetchCacheOptions, type FetchDriverOptions, type FetchError, type FetchFailure, type FetchInit, type FetchInvalidate, type FetchRequest, type FetchResponse, type FetchRetry, type FetchSource, type FieldErrors, type Filter, type FixDrivers, type FormActions, type FormCalculated, type FormData, type FormField, type FormFieldCheck, type FormOptions, type FormSource, type FormState, type FormTool, type FormToolHandle, type FormToolResult, type FromAISDKOptions, type HeadValue, type HotModuleAPI, type HttpTransportOptions, type InspectAction, type InspectActionTrigger, type InspectChild, type InspectCommand, type InspectComponent, type InspectDiagnostic, type InspectFix, type InspectGraph, type InspectRecentAction, type InspectRelatedLocation, type InspectSelector, type InspectTextEdit, type InspectTimer, type InstallPrompt, type IntentSources, type IntrinsicControlProps, type JsonSchemaObject, type Layout, type LayoutNode, type LazyComponent, type LazyOptions, type Lens, type Lense, MainDOMSource, type McpAppDisplayMode, type McpAppDriverOptions, type McpAppError, type McpAppRequest, type McpAppSource, type McpContentBlock, type McpDownloadItem, type McpHostContext, type McpHostInfo, type McpLogLevel, type McpResourceContents, type McpSamplingRequest, type McpToolResult, type MockConfig, MockedDOMSource, type NonStateSinkReturns, type OpenResponsesEvent, type OpenResponsesOptions, type PagerActions, type PagerCalculated, type PagerOptions, type PagerState, type ParamNames, type ParentPayloadOf, type Persist, type PersistOptions, type PersistOptionsFor, type PersistStorage, type PersistedEntry, Portal, type PortalProps, type ProcessFormOptions, type QueryCache, type QueryCacheSnapshot, type QueryCacheSnapshotEntry, type Ref, type Ref$, type RegisteredEvent, type RenderOptions, type RenderResult, type RenderToStringOptions, type RenderableComponent, type ReplyRequest, type Resource, type ResourceRequest, type RootComponent, type Route, type RouteName, type RouteParamsArg, type RouteQuery, type Router, type RouterBlocked, type RouterCommand, type RouterOptions, type RouterSource, type RunOptions, type SchemaOutput, type ScrollToAlign, type SelectedDOMSource, type SelectionActions, type SelectionCalculated, type SelectionOptions, type SelectionState, type ServiceWorkerCommand, type ServiceWorkerOptions, type ServiceWorkerSource, type SimulatedEventInit, Slot, type SlotProps, type SocketActions, type SocketClose, type SocketConnection, type SocketDriverOptions, type SocketError, type SocketEvent, type SocketOpen, type SocketReconnect, type SocketRequest, type SocketSource, type SortFunction, type SortObject, type SortSpec, type SortableActions, type SortableDropped, type SortableOptions, type SortableState, type SseConnection, type StandardSchemaLike, type StateProp, type StrictDialect, type StrictSchemas, Suspense, type SuspenseProps, Switchable, type SwitchableProps, type SygnalApp, type SygnalBodyDOMSource, type SygnalDOMSource, type SygnalDevTools, type SygnalDocumentDOMSource, type SygnalEvents, type SygnalSinks, type TestAction, type Thunk, type ThunkData, type TimerAfter, type TimerFrame, type TimerSpec, type TimerTick, type Timers, Transition, type TransitionProps, type UIMessageStreamOptions, type UidFunction, type UndoBehaviorOptions, type UndoHistory, type UndoOptions, type UsesActions, type UsesState, type ViewProps, VirtualCollection, type VirtualCollectionProps, type WebMcpHandle, type Widget, type WidgetDefinition, type WidgetDispatch, type WidgetElementOf, type WidgetEmit, type WidgetHandle, type WidgetHostProps, type WithinTarget, abort, agentTools, agui, answers, anthropicMessages, askCard, byId, chat, chatCompletions, checkForm, choice, chromePrompt, classes, clearDiagnostics, clipboardSource, commandBar, compose, composeWith, controls, createCommand, createInstallPrompt, createRef, createRef$, decide, defineBehavior, defineCatalog, defineComponent, defineWidget, driverFromAsync, emit, enableHMR, encodeOpenResponses, event, exactState, experimentalExposeWebMcp, fieldName, fieldNames, focusInvalid, focusWithin, form, formErrors, formTool, fromAISDK, fromTree, geolocationSource, getDevTools, getDiagnostics, getField, hasField, intersectionSource, isSelected, jsonSchema, lazy, makeBrowserDriver, makeBrowserDriverWith, makeChatDriver, makeDOMDriver, makeDragDriver, makeFetchDriver, makeHeadDriver, makeMcpAppDriver, makeRouter, makeRouterDriver, makeServiceWorkerDriver, makeSocketDriver, makeTimerDriver, makeViewTransitionDOMDriver, mediaSource, messageText, mockDOMSource, noul, onDiagnostic, onlineSource, onlineStatus$, openResponses, openToolCalls, outputJsonSchema, pager, parseInput, persist, portal, processDrag, processForm, queryCache, removeNode, renderComponent, renderHead, renderToString, replyErrors, resizeSource, run, score, selection, set, setField, sortable, storageSource, strictSchemas, thunk, toJsonSchema, toTree, toggle, uiMessageStream, undo, undoable, visibilitySource, withToolResults, xs };
+export { ABORT, type ActionCause, type ActionsOf, type ActiveTimer, type AgentAction, type AgentConfirm, type AgentConfirmInfo, type AgentDeclaration, type AgentIssue, type AgentQuery, type AgentQueryResult, type AgentResult, type AgentSchema, type AgentTool, type AgentToolSet, type AgentToolsOptions, type AguiOptions, type AnswerPick, type AnswerPicks, type AnthropicMessagesOptions, type AnyComponentModule, type AnyControl, type AppErrorHook, type AppErrorInfo, type AppErrorPhase, type ArrayKeysOf, type ArrayPathsOf, type AsyncDriverError, type AsyncDriverFromFunction, type AsyncRequest, type Behavior, type BehaviorDefinition, type BehaviorFactory, type BehaviorHandler, type BehaviorModelEntry, type BehaviorProps, type BehaviorSources, type BehaviorState, type BehaviorTarget, type BrowserCommand, type BrowserFake, type BrowserFakeOptions, type BrowserIntersection, type BrowserPosition, type BrowserResize, type BrowserSource, type BrowserSources, type BrowserSpec, type Catalog, type CatalogContainer, type CatalogContainerDecl, type CatalogDecl, type CatalogOption, type CatalogParam, type CatalogParamValue, type CatalogParamsOf, type CatalogPart, type CatalogPartDecl, type CatalogRecord, type CatalogTree, type CatalogTreeNode, type ChatAbort, type ChatActions, type ChatAskOptions, type ChatCall, type ChatCard, type ChatCardStatus, type ChatClientTool, type ChatCompletionsOptions, type ChatDelta, type ChatDone, type ChatDriverOptions, type ChatError, type ChatEvent, type ChatOk, type ChatOptions, type ChatOutputOf, type ChatOutputSchema, type ChatRequest, type ChatSource, type ChatState, type ChatStatus, type ChatTool, type ChatToolCall, type ChatToolPart, type ChatTransport, type ChatUsage, type ChromePromptOptions, type ChromePromptStatus, type ChromePromptTransport, type ClassesType, Collection, type CollectionFrom, type CollectionProps, type Command, type CommandBarActions, type CommandBarOptions, type CommandBarResult, type CommandBarState, type CommandBarStatus, type CommandBarUnsure, type CommandSource, type Component, type ComposeActions, type ComposeAnswer, type ComposeBackend, type ComposeNames, type ComposeOptions, type ComposeRenderOptions, type ComposeRenderable, type ComposeState, type ComposeStatus, type ComposeTree, Composed, type ComposedProps, type Connections, type ContainerView, type Control, type ControlCommonProps, type ControlDOMSource, type ControlElementOf, type ControlEvent, type ControlH, type ControlPropsOf, type ControlSpec, type ControlSpecObject, type ControlsOf, type ConvertedSchema, type CycleDOMEvent, type CycleDriver, type DOMDriverOptions, type DOMEventShorthand, type DOMEventShorthands, type DOMSource, type DefaultDrivers, type DefineComponentOptions, type DevToolsActionCause, type DevToolsCopyAsTestOptions, type DevToolsSessionRecording, 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 ElementCommand, type ElementCommandRegistry, type ElementCommands, type ElementProps, type ElementTarget, type EmittedEvent, type EnrichedEventStream, type Event$1 as Event, type EventName, type EventPayload, type EventPayloadFunction, type EventSink, type EventsFnOptions, type EventsSource, type ExactShape, type ExplainedAction, type ExposeWebMcpOptions, type FakeCacheEntry, type FakeChatChunk, type FakeConnection, type FakeConnectionTarget, type FakeReplyOptions, type FetchCacheOptions, type FetchDriverOptions, type FetchError, type FetchFailure, type FetchInit, type FetchInvalidate, type FetchRequest, type FetchResponse, type FetchRetry, type FetchSource, type FieldErrors, type Filter, type FixDrivers, type FormActions, type FormCalculated, type FormData, type FormField, type FormFieldCheck, type FormOptions, type FormSource, type FormState, type FormTool, type FormToolHandle, type FormToolResult, type FromAISDKOptions, type HeadValue, type HotModuleAPI, type HttpTransportOptions, type InspectAction, type InspectActionTrigger, type InspectChild, type InspectChildSelect, type InspectCommand, type InspectComponent, type InspectDiagnostic, type InspectFix, type InspectGraph, type InspectLocation, type InspectRecentAction, type InspectRelatedLocation, type InspectSelector, type InspectTextEdit, type InspectTimer, type InstallPrompt, type IntentSources, type IntrinsicControlProps, type JsonSchemaObject, type Layout, type LayoutNode, type LazyComponent, type LazyOptions, type Lens, type Lense, MainDOMSource, type McpAppDisplayMode, type McpAppDriverOptions, type McpAppError, type McpAppRequest, type McpAppSource, type McpContentBlock, type McpDownloadItem, type McpHostContext, type McpHostInfo, type McpLogLevel, type McpResourceContents, type McpSamplingRequest, type McpToolResult, type MockConfig, MockedDOMSource, type NonStateSinkReturns, type OpenResponsesEvent, type OpenResponsesOptions, type PagerActions, type PagerCalculated, type PagerOptions, type PagerState, type ParamNames, type ParentPayloadOf, type Persist, type PersistOptions, type PersistOptionsFor, type PersistStorage, type PersistedEntry, Portal, type PortalProps, type ProcessFormOptions, type QueryCache, type QueryCacheSnapshot, type QueryCacheSnapshotEntry, type Ref, type Ref$, type RegisteredEvent, type RenderOptions, type RenderResult, type RenderToStringOptions, type RenderableComponent, type ReplyRequest, type Resource, type ResourceRequest, type RootComponent, type Route, type RouteName, type RouteParamsArg, type RouteQuery, type Router, type RouterBlocked, type RouterCommand, type RouterOptions, type RouterSource, type RunOptions, type SchemaOutput, type ScrollToAlign, type SelectedDOMSource, type SelectionActions, type SelectionCalculated, type SelectionOptions, type SelectionState, type ServiceWorkerCommand, type ServiceWorkerOptions, type ServiceWorkerSource, type SimulatedEventInit, Slot, type SlotProps, type SocketActions, type SocketClose, type SocketConnection, type SocketDriverOptions, type SocketError, type SocketEvent, type SocketOpen, type SocketReconnect, type SocketRequest, type SocketSource, type SortFunction, type SortObject, type SortSpec, type SortableActions, type SortableDropped, type SortableOptions, type SortableState, type SseConnection, type StandardSchemaLike, type StateProp, type StrictDialect, type StrictSchemas, Suspense, type SuspenseProps, Switchable, type SwitchableProps, type SygnalApp, type SygnalBodyDOMSource, type SygnalDOMSource, type SygnalDevTools, type SygnalDocumentDOMSource, type SygnalEvents, type SygnalSinks, type TestAction, type Thunk, type ThunkData, type TimerAfter, type TimerFrame, type TimerSpec, type TimerTick, type Timers, Transition, type TransitionProps, type UIMessageStreamOptions, type UidFunction, type UndoBehaviorOptions, type UndoHistory, type UndoOptions, type UsesActions, type UsesState, type ViewProps, VirtualCollection, type VirtualCollectionProps, type WebMcpHandle, type Widget, type WidgetDefinition, type WidgetDispatch, type WidgetElementOf, type WidgetEmit, type WidgetHandle, type WidgetHostProps, type WithinTarget, abort, agentTools, agui, answers, anthropicMessages, askCard, byId, chat, chatCompletions, checkForm, choice, chromePrompt, classes, clearDiagnostics, clipboardSource, commandBar, compose, composeWith, controls, createCommand, createInstallPrompt, createRef, createRef$, decide, defineBehavior, defineCatalog, defineComponent, defineWidget, driverFromAsync, emit, enableHMR, encodeOpenResponses, event, exactState, experimentalExposeWebMcp, fieldName, fieldNames, focusInvalid, focusWithin, form, formErrors, formTool, fromAISDK, fromTree, geolocationSource, getDevTools, getDiagnostics, getField, hasField, intersectionSource, isSelected, jsonSchema, lazy, makeBrowserDriver, makeBrowserDriverWith, makeChatDriver, makeDOMDriver, makeDragDriver, makeFetchDriver, makeHeadDriver, makeMcpAppDriver, makeRouter, makeRouterDriver, makeServiceWorkerDriver, makeSocketDriver, makeTimerDriver, makeViewTransitionDOMDriver, mediaSource, messageText, mockDOMSource, noul, onDiagnostic, onlineSource, onlineStatus$, openResponses, openToolCalls, outputJsonSchema, pager, parseInput, persist, portal, processDrag, processForm, queryCache, removeNode, renderComponent, renderHead, renderToString, replyErrors, resizeSource, run, score, selection, set, setField, sortable, storageSource, strictSchemas, thunk, toJsonSchema, toTree, toggle, uiMessageStream, undo, undoable, visibilitySource, withToolResults, xs };

package/dist/index.esm.js

@@ -702,6 +702,9 @@ const DEV_CODE_SEVERITY = {
     SYG128: 'error',
     // PLAN-4 4-G2: static only (sygnal-check); listed so the entry knows its title
     SYG129: 'warn',
+    // PLAN-10 X-1: static only (sygnal-check)
+    SYG170: 'warn',
+    SYG171: 'warn',
     SYG221: 'error',
     // PLAN-4 GS-4 (state.ts)
     SYG222: 'warn',
@@ -768,6 +771,8 @@ const DEV_CODE_SEVERITY = {
     SYG426: 'warn',
     // checks/next.ts: CHILD.select(undefined), usually a missing export
     SYG427: 'error',
+    // checks/next.ts: a path designator that 6.4 read as one key with a dot
+    SYG428: 'warn',
     // PLAN-9 (checks/next.ts): D470 key identity, two children with one identity
     SYG453: 'warn',
     SYG612: 'error',
@@ -1394,18 +1399,45 @@ function localCell(app, parent) {
     return { local: true, get: () => (own ? v : parent.get()), set: (n) => { v = n; own = true; app.commit(); } };
 }
 /**
- * state="key". `owner`: the parent's name when `k` is one of its calculated fields (SYG409:
- * writes ignored; `what` names the writer in the message). `dflt`: an isolated child's
- * initialState, read while the slice is undefined. `has()`: the slice itself is defined (D174).
+ * SPIKE (state paths): a state designator as segments. A plain key is one segment; 'a.b.0' and
+ * 'a[0].b' are paths into nested objects and arrays. No array form: an array `from` / `state` is
+ * the data passed by mistake (SYG410 / SYG412), and ['x', 'y'] would be ambiguous.
+ */
+const pathOf$1 = (p) => p.replace(/\[(\d+)\]/g, '.$1').split('.');
+const getIn$1 = (o, ks) => { for (const k of ks) {
+    if (o == null)
+        return undefined;
+    o = o[k];
+} return o; };
+/** `o` with the value at `ks` replaced; only the levels on the path are copied (a missing level becomes {}) */
+function setIn$1(o, ks, i, v) {
+    if (i == ks.length)
+        return v;
+    const k = ks[i], cur = o?.[k], n = setIn$1(cur, ks, i + 1, v);
+    if (n === cur && o != null)
+        return o;
+    if (Array.isArray(o)) {
+        const c = o.slice();
+        c[k] = n;
+        return c;
+    }
+    return { ...o, [k]: n };
+}
+/**
+ * state="key" (SPIKE: or a path, 'a.b' / 'a[0].b'). `owner`: the parent's name when the first
+ * segment is one of its calculated fields (SYG409: writes ignored; `what` names the writer in
+ * the message). `dflt`: an isolated child's initialState, read while the slice is undefined.
+ * `has()`: the slice itself is defined (D174).
  */
 function keyCell(parent, k, owner, dflt, what = 'Sub-component') {
+    const ks = pathOf$1(k);
     let lp = {}, lv;
     return {
         get() {
             const p = parent.get();
             if (p !== lp) {
                 lp = p;
-                lv = p == null ? undefined : p[k];
+                lv = getIn$1(p, ks);
                 if (lv === undefined)
                     lv = dflt;
             }
@@ -1413,12 +1445,12 @@ function keyCell(parent, k, owner, dflt, what = 'Sub-component') {
         },
         set(v) {
             if (owner)
-                return warn('SYG409', owner, `${what} tried to update calculated field '${k}'; ignored`, 'Bind it to a non-calculated field');
+                return warn('SYG409', owner, `${what} tried to update calculated field '${ks[0]}'; ignored`, 'Bind it to a non-calculated field');
             const p = parent.get();
-            if (p?.[k] !== v)
-                parent.set({ ...p, [k]: v });
+            if (getIn$1(p, ks) !== v)
+                parent.set(setIn$1(p, ks, 0, v));
         },
-        has: () => parent.get()?.[k] !== undefined,
+        has: () => getIn$1(parent.get(), ks) !== undefined,
     };
 }
 /**
@@ -1653,6 +1685,8 @@ class View {
     get state() { return this.i.cell.get(); }
     get props() { return this.i.props; }
     get context() { return this.i.context(); }
+    /** D530: the context keys the last render's view read (null: none rendered, or no context) */
+    get reads() { return this.i.keys; }
     get isRoot() { return !this.i.parent; }
     get kind() { return this.i.kind; }
     /** false on a hidden Switchable page and below it */
@@ -2038,9 +2072,11 @@ function isEqualNamespace(a, b) {
     return true;
 }
 // G-261: a DOM change Sygnal makes outside a patch (a Transition's leave, a Portal mounted late)
-// re-emits the DOM source of the app whose root contains `el` (makeDOMDriver listens on its root)
+// re-emits the DOM source of the app whose root contains `el` (makeDOMDriver listens on its root).
+// The event comes from the element's own window: jsdom refuses an `Event` from another realm (a
+// Transition's leave timer that fires after a jsdom test environment was torn down)
 const POKE = 'sygnal-dom';
-const pokeDOM = (el) => el?.dispatchEvent(new Event(POKE, { bubbles: true }));
+const pokeDOM = (el) => el?.dispatchEvent(new (el.ownerDocument?.defaultView?.Event || Event)(POKE, { bubbles: true }));
 const obj = (o) => o !== null && typeof o == 'object' && !Array.isArray(o);
 /**
  * P46-P: two vnodes' data are the same for the DOM modules: the same keys, each value identical
@@ -2764,7 +2800,7 @@ class Inst {
                 fail$2('SYG405', def.name, 'Sub-component initialState replaces the state its parent passes in', 'Remove initialState, or set isolatedState = true');
             }
             const dflt = def.isolated ? def.initialState : undefined;
-            const cell = typeof st == 'string' ? keyCell(this.cell, st, calcOf?.has(st) && this.def.name, dflt)
+            const cell = typeof st == 'string' ? keyCell(this.cell, st, calcOf?.has(pathOf$1(st)[0]) && this.def.name, dflt)
                 : st !== undefined ? lensCell(this.cell, st, this.def.name, (e) => app.appError(this, e, 'view'), dflt)
                     : def.isolated ? localCell(app, this.cell) : this.cell;
             const scope = app.scope();
@@ -2846,8 +2882,9 @@ class Inst {
  *
  * It stands where the `<Collection>` marker was in its owner's template and renders the items
  * inside the owner's render: no stream of its own, no pickCombine.
- * - `of`: a component function (D163: no names). `from`: a state key (SYG409 on a calculated
- *   one), a `{ get, set }` lens (SYG412 without get(); SYG401 for a non-array) or none (the
+ * - `of`: a component function (D163: no names). `from`: a state key or path ('board.cards';
+ *   SYG409 on a calculated first segment; SYG401 when it isn't an array: the dev entry's), a
+ *   `{ get, set }` lens (SYG412 without get(); SYG401 for a non-array) or none (the
  *   owner's state is the array).
  * - Items are keyed by `id`, an id-less item by its raw index (D169); one key -> index map per
  *   array identity serves every item (cell.ts indexer). A duplicate key renders its first element
@@ -2929,16 +2966,9 @@ function arrayCell(owner, from) {
             set: (v) => oc.set(v),
         };
     }
-    if (typeof from == 'string') {
-        const cs = oc.get(), calc = owner.def.calcNames?.has(from);
-        if (isObj$2(cs) && !(from in cs) && !calc) {
-            const arrays = Object.keys(cs).filter(k => Array.isArray(cs[k]));
-            warn('SYG401', name, `Collection from="${from}" is not in state${arrays.length ? ` (array fields: '${arrays.join("', '")}')` : ''}; it renders nothing until it exists`, 'Set it to an array in initialState');
-        }
-        else if (isObj$2(cs) && !Array.isArray(cs[from]))
-            warn('SYG401', name, `Collection 'from' field '${from}' is not an array; it renders nothing`, 'Set it to an array in initialState');
-        return keyCell(oc, from, calc && name, undefined, 'Collection');
-    }
+    // a key or a path ('board.cards'); SYG401 for one that isn't an array is the dev entry's (checks/collections.ts)
+    if (typeof from == 'string')
+        return keyCell(oc, from, owner.def.calcNames?.has(pathOf$1(from)[0]) && name, undefined, 'Collection');
     if (isObj$2(from) && typeof from.get == 'function') {
         let lp = {}, lv;
         return {
@@ -4147,7 +4177,7 @@ class SwitchableHost {
         this.lr = true;
         this.kids = [];
         check$3(owner, props);
-        const st = props.state, calc = typeof st == 'string' && owner.def.calcNames?.has(st);
+        const st = props.state, calc = typeof st == 'string' && owner.def.calcNames?.has(pathOf$1(st)[0]);
         this.cell = typeof st == 'string' ? keyCell(owner.cell, st, calc && owner.def.name, undefined, 'Switchable sub-component')
             : st !== undefined ? lensCell(owner.cell, st, owner.def.name, (e) => owner.app.appError(owner, e, 'view'))
                 : owner.cell;