@almadar/ui 6.0.0 → 6.2.0

package/dist/components/index.d.ts

@@ -1,18 +1,19 @@
 import * as React$1 from 'react';
 import React__default, { ReactNode, ErrorInfo } from 'react';
-import { Asset, EventKey, EventPayload, EventEmit, AssetUrl, JsonObject, EntityRow, FieldValue, EntityRole, AnimationName, SpriteDirection, AnimationDef, ScenePos, Camera, EntityWith, TraitConfigValue, JsonValue, AssetCatalog, EventPayloadValue, DeclaredTraitConfig, TraitConfig, OrbitalSchema, Trait, OrbitalEntity, UISlot, EditFocus, TraceSubagent, TraceActivity, TraceChatMessage } from '@almadar/core';
+import { Asset, EventKey, EventPayload, EventEmit, AssetUrl, FieldValue, EntityRow, EntityRole, AnimationName, SpriteDirection, AnimationDef, ScenePos, Camera, EntityWith, TraitConfigValue, JsonValue, AssetCatalog, JsonObject, EventPayloadValue, DeclaredTraitConfig, TraitConfig, ControlValue, OrbitalSchema, Trait, OrbitalEntity, FormSubmitPayload, UISlot, EditFocus, TraceSubagent, TraceActivity, TraceChatMessage } from '@almadar/core';
 export { AnimationDef, AnimationName, BusEvent, BusEventListener, BusEventSource, BusEventListener as EventListener, SpriteDirection, UISlot, Unsubscribe } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 import { C as ColorToken, U as UiError, P as Point, L as LinkAction, I as ImageSource } from '../types-B3nHgnMG.js';
 export { R as Rect } from '../types-B3nHgnMG.js';
 import { SExpr } from '@almadar/evaluator';
-import { U as UnitAnimationState, F as FacingDirection, S as SpriteSheetUrls, g as SpriteFrameDims, R as ResolvedFrame, h as CanvasLighting, i as CanvasPost, a as IsometricUnit, j as CameraState, k as FieldInfo, l as OrbitalTraitInfo, m as OrbitalPageInfo, T as TraitLevelData, E as ExternalLink } from '../avl-schema-parser-CLIm28Wa.js';
-export { B as BoardTile, G as GameAction, n as GamePhase, o as GameState, p as GameUnit, b as IsometricFeature, I as IsometricTile, P as Position, q as UnitTrait, r as calculateAttackTargets, s as calculateValidMoves, t as createInitialGameState } from '../avl-schema-parser-CLIm28Wa.js';
-import { D as DrawableNode, F as FxOverlayItem, M as MeshShapeKind, a as MeshMaterial, b as DrawGroupProps, c as DrawTextProps, d as DrawMeshProps } from '../paintDispatch-B5n2DTB-.js';
-export { e as FxOverlayKind } from '../paintDispatch-B5n2DTB-.js';
+import { U as UnitAnimationState, F as FacingDirection, S as SpriteSheetUrls, g as SpriteFrameDims, R as ResolvedFrame, h as CanvasLighting, i as CanvasPost, a as IsometricUnit, j as CameraState, k as FieldInfo, l as OrbitalTraitInfo, m as OrbitalPageInfo, T as TraitLevelData, E as ExternalLink } from '../avl-schema-parser-dvJKXn-o.js';
+export { B as BoardTile, G as GameAction, n as GamePhase, o as GameState, p as GameUnit, b as IsometricFeature, I as IsometricTile, P as Position, q as UnitTrait, r as calculateAttackTargets, s as calculateValidMoves, t as createInitialGameState } from '../avl-schema-parser-dvJKXn-o.js';
+import { D as DrawableNode, P as Projector, F as FxOverlayItem, M as MeshShapeKind, a as MeshMaterial, b as DrawGroupProps, c as DrawTextProps, d as DrawMeshProps } from '../paintDispatch-B5ObLnUv.js';
+export { e as FxOverlayKind } from '../paintDispatch-B5ObLnUv.js';
 export { A as AudioManifest, G as GameAudioContext, a as GameAudioContextValue, e as GameAudioControls, b as GameAudioProvider, c as GameAudioProviderProps, S as SoundEntry, U as UseGameAudioOptions, f as useGameAudio, u as useGameAudioContext } from '../GameAudioProvider-B48iXwz3.js';
-import { C as ContentSegment, L as LessonSegment, U as InteractiveOrbitalType, b as DomLayoutData, d as DomStateNode, V as VisualizerConfig, e as DomTransitionLabel } from '../cn-CFurBb2q.js';
-export { W as BloomLevel, X as BloomQuizBlock, Y as BloomQuizBlockProps, Z as MixedSegment, n as cn, A as parseLessonSegments, _ as parseMarkdownWithCodeBlocks } from '../cn-CFurBb2q.js';
+import { EmojiPickPayload, SelectionChangePayload, ItemActionPayload } from '@almadar/core/patterns';
+import { C as ContentSegment, L as LessonSegment, U as InteractiveOrbitalType, b as DomLayoutData, d as DomStateNode, V as VisualizerConfig, e as DomTransitionLabel } from '../cn-BbhJq_nr.js';
+export { W as BloomLevel, X as BloomQuizBlock, Y as BloomQuizBlockProps, Z as MixedSegment, n as cn, A as parseLessonSegments, _ as parseMarkdownWithCodeBlocks } from '../cn-BbhJq_nr.js';
 import { b as SlotContent, d as SlotPropValue } from '../useUISlots-GNwGLlW2.js';
 export { D as DEFAULT_SLOTS, S as SlotAnimation, a as SlotChangeCallback, c as SlotRenderConfig, U as UISlotManager, u as useUISlotManager } from '../useUISlots-GNwGLlW2.js';
 export { ALMADAR_DND_MIME, AuthContextValue, AuthUser, CanvasGestureCallbacks, CanvasGestureHandlers, CompileResult, CompileStage, DragReorderResult, DraggablePayload, Extension, ExtensionManifest, FileSystemFile, FileSystemStatus, GitHubRepo, GitHubStatus, HistoryChangeSummary, HistoryTimelineItem, I18nContextValue, I18nProvider, InfiniteScrollOptions, InfiniteScrollResult, LongPressHandlers, LongPressOptions, OpenFile, Positioned, PullToRefreshOptions, PullToRefreshResult, QuerySingletonEntity, QuerySingletonResult, QuerySingletonState, QueryState, RenderInterpolationHandle, RenderInterpolationOptions, RevertResult, SelectedFile, SharedEntityStore, SharedEntityStoreContext, SharedEntitySubscriber, SharedEntityWriter, SwipeGestureOptions, SwipeGestureResult, SwipeHandlers, TapRevealOptions, TapRevealResult, TraitListenSpec, TranslateFunction, UseCanvasGesturesOptions, UseCompileResult, UseDraggableOptions, UseDraggableResult, UseDropZoneOptions, UseDropZoneResult, UseExtensionsOptions, UseExtensionsResult, UseFileEditorOptions, UseFileEditorResult, UseFileSystemResult, UseOrbitalHistoryOptions, UseOrbitalHistoryResult, createSharedEntityStore, createTranslate, parseQueryBinding, runTickFrame, useAgentChat, useAuthContext, useCanvasGestures, useCompile, useConnectGitHub, useDeepAgentGeneration, useDisconnectGitHub, useDragReorder, useDraggable, useDropZone, useExtensions, useFileEditor, useFileSystem, useGitHubBranches, useGitHubRepo, useGitHubRepos, useGitHubStatus, useInfiniteScroll, useLongPress, useMediaQuery, useOrbitalHistory, usePreview, usePullToRefresh, useQuerySingleton, useRenderInterpolation, useSharedEntitySnapshot, useSharedEntityStore, useSharedEntityStoreContext, useSwipeGesture, useTapReveal, useTraitListens, useTranslate, useUIEvents, useValidation } from '../hooks/index.js';
@@ -287,7 +288,9 @@ interface ButtonProps extends React__default.ButtonHTMLAttributes<HTMLButtonElem
     iconAsset?: Asset;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Button label text (alternative to children for schema-driven rendering) */
     label?: string;
@@ -312,7 +315,9 @@ interface InputProps extends Omit<React__default.InputHTMLAttributes<HTMLInputEl
     /** Whether input is disabled */
     disabled?: boolean;
     /** Declarative event name for trait dispatch */
-    action?: EventKey;
+    action?: EventEmit<{
+        value: string | number;
+    }>;
     /**
      * Input type — selects the field's data mode. Use 'password' for masked
      * credentials / secret / passphrase entry (there is no separate password
@@ -337,7 +342,11 @@ interface InputProps extends Omit<React__default.InputHTMLAttributes<HTMLInputEl
     /** Rows for textarea type */
     rows?: number;
     /** onChange handler or declarative event key for trait dispatch */
-    onChange?: React__default.ChangeEventHandler<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement> | EventKey;
+    onChange?: React__default.ChangeEventHandler<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement> | EventEmit<{
+        value: string;
+    } | {
+        checked: boolean;
+    }>;
 }
 declare const Input: React__default.ForwardRefExoticComponent<InputProps & React__default.RefAttributes<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>>;
 
@@ -365,7 +374,9 @@ interface TextareaProps extends Omit<React__default.TextareaHTMLAttributes<HTMLT
     /** Error message */
     error?: string;
     /** onChange handler or declarative event key for trait dispatch */
-    onChange?: React__default.ChangeEventHandler<HTMLTextAreaElement> | EventKey;
+    onChange?: React__default.ChangeEventHandler<HTMLTextAreaElement> | EventEmit<{
+        value: string;
+    }>;
 }
 declare const Textarea: React__default.ForwardRefExoticComponent<TextareaProps & React__default.RefAttributes<HTMLTextAreaElement>>;
 
@@ -406,7 +417,9 @@ interface SelectProps extends Omit<React__default.SelectHTMLAttributes<HTMLSelec
     /** Show a clear button when a value is selected. */
     clearable?: boolean;
     /** onChange handler (native ChangeEvent) or declarative event key for trait dispatch */
-    onChange?: React__default.ChangeEventHandler<HTMLSelectElement> | EventKey;
+    onChange?: React__default.ChangeEventHandler<HTMLSelectElement> | EventEmit<{
+        value: string | string[];
+    }>;
     /** Value-based change: a React callback (internal use) OR a declarative event
      *  key that emits `{ value }` on the bus (render-ui / lolo authoring). Mirrors
      *  the `onChange` handler|event convention so it's an event-emitting prop, not a
@@ -426,7 +439,9 @@ interface CheckboxProps extends Omit<React__default.InputHTMLAttributes<HTMLInpu
     defaultChecked?: boolean;
     label?: string;
     /** onChange handler or declarative event key for trait dispatch */
-    onChange?: React__default.ChangeEventHandler<HTMLInputElement> | EventKey;
+    onChange?: React__default.ChangeEventHandler<HTMLInputElement> | EventEmit<{
+        checked: boolean;
+    }>;
 }
 declare const Checkbox: React__default.ForwardRefExoticComponent<CheckboxProps & React__default.RefAttributes<HTMLInputElement>>;
 
@@ -682,7 +697,9 @@ interface AvatarProps {
     onClick?: () => void;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
 }
 declare const Avatar: React__default.FC<AvatarProps>;
@@ -738,10 +755,14 @@ interface BoxProps extends React__default.HTMLAttributes<HTMLDivElement> {
     as?: React__default.ElementType;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
-    hoverEvent?: EventKey;
+    hoverEvent?: EventEmit<{
+        hovered: boolean;
+    }>;
     /** When true (default), a touch/pen tap also fires `hoverEvent` (toggling hovered) so hover-only reveals work on touch. */
     tapReveal?: boolean;
     /** Maximum width (CSS value, e.g., "550px", "80rem") */
@@ -895,7 +916,9 @@ interface RadioProps extends Omit<React__default.InputHTMLAttributes<HTMLInputEl
     /** Current selected value */
     value?: string;
     /** Declarative event name for trait dispatch */
-    action?: EventKey;
+    action?: EventEmit<{
+        value: string;
+    }>;
     /**
      * Label text displayed next to the radio button
      */
@@ -1028,7 +1051,9 @@ interface StackProps {
     tabIndex?: number;
     /** Declarative event name — emits UI:{action} via eventBus on click */
     action?: EventKey;
-    /** Payload to include with the action event */
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
     responsive?: boolean;
@@ -1095,9 +1120,14 @@ interface TextHighlightProps {
      */
     children: React__default.ReactNode;
     /** Declarative event name — emits UI:{action} via eventBus on click */
-    action?: EventKey;
-    /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } */
-    hoverEvent?: EventKey;
+    action?: EventEmit<{
+        annotationId?: string;
+    }>;
+    /** Declarative hover event — emits UI:{hoverEvent} with { hovered, annotationId } */
+    hoverEvent?: EventEmit<{
+        hovered: boolean;
+        annotationId?: string;
+    }>;
 }
 /**
  * TextHighlight component for rendering highlighted text annotations
@@ -1330,10 +1360,10 @@ declare const Aside: React__default.ForwardRefExoticComponent<AsideProps & React
  * Context for conditional evaluation
  */
 type ConditionalContext = {
-    formValues: JsonObject;
-    globalVariables: JsonObject;
-    localVariables?: JsonObject;
-    entity?: JsonObject;
+    formValues: Record<string, FieldValue>;
+    globalVariables: Record<string, FieldValue>;
+    localVariables?: Record<string, FieldValue>;
+    entity?: Record<string, FieldValue>;
 };
 interface ConditionalWrapperProps {
     /** The S-expression condition to evaluate */
@@ -1542,8 +1572,12 @@ interface RangeSliderProps extends Omit<React__default.HTMLAttributes<HTMLDivEle
     /** Disabled state */
     disabled?: boolean;
     /** Declarative event name for value changes */
-    action?: EventKey;
-    /** Payload to include with the action event */
+    action?: EventEmit<{
+        value: number;
+    }>;
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Direct onChange callback */
     onChange?: (value: number) => void;
@@ -1586,7 +1620,9 @@ declare const AnimatedCounter: React__default.FC<AnimatedCounterProps>;
 interface InfiniteScrollSentinelProps {
     /** Event name to emit when load-more is triggered (emitted as UI:{loadMoreEvent}) */
     loadMoreEvent: EventKey;
-    /** Optional payload to include with the load-more event */
+    /** Optional payload to include with the load-more event
+     *  @payloadFor loadMoreEvent
+     */
     loadMorePayload?: EventPayload;
     /** Whether a load operation is currently in progress */
     isLoading?: boolean;
@@ -2068,8 +2104,10 @@ declare const SHEET_COLUMNS = 8;
 /**
  * Standard sprite sheet row layout.
  * Row 0 = idle, Row 1 = walk, Row 2 = attack, Row 3 = hit, Row 4 = death.
+ * Partial: platformer names (skate/jump/fall) have no row on this sheet — they
+ * resolve through an atlas manifest, never through this constant fallback.
  */
-declare const SPRITE_SHEET_LAYOUT: Record<AnimationName, AnimationDef>;
+declare const SPRITE_SHEET_LAYOUT: Partial<Record<AnimationName, AnimationDef>>;
 
 interface HealthBarProps {
     /** Current value */
@@ -2447,7 +2485,9 @@ interface StateGraphProps {
     /** Graph canvas height. */
     height?: number;
     /** Emits UI:{nodeClickEvent} with { stateId } when a node is clicked. */
-    nodeClickEvent?: EventKey;
+    nodeClickEvent?: EventEmit<{
+        stateId: string;
+    }>;
     className?: string;
 }
 declare function StateGraph({ states, transitions, currentState, selectedState, addingFrom, initialState, width, height, nodeClickEvent, className, }: StateGraphProps): React$1.JSX.Element;
@@ -3486,7 +3526,7 @@ interface GameShellProps {
     backgroundAsset?: Asset;
     /** Per-call-site 9-sliced panel override. Chrome normally comes from the active theme; most callers leave this unset. */
     hudBackgroundAsset?: Asset;
-    /** Game display-font key (future | future-narrow | pixel | blocks | mini) or a CSS font-family. Scoped override of the theme contract's --font-family-display slot: titles and numerics take this face, body text follows the active theme. */
+    /** Game display-font key (pixel | fredoka | future | future-narrow | blocks | mini) or a CSS font-family. Scoped override of the theme contract's --font-family-display slot: titles and numerics take this face, body text follows the active theme. Unset = the theme token decides. */
     fontFamily?: string;
     /** Scopes an `@almadar/ui` theme (e.g. "game-sci-fi-dark") to this shell's subtree. */
     "data-theme"?: string;
@@ -3604,6 +3644,16 @@ interface LearningCanvasProps {
     backgroundColor?: string;
     /** Declarative shapes to draw. */
     shapes?: LearningShape[];
+    /**
+     * Neutral game-canvas drawables (e.g. `draw-sprite`, `draw-fx-layer`) painted
+     * in world coordinates via the supplied `projector`. This lets the learning
+     * canvas reuse the game drawable vocabulary without reimplementing sprites/FX.
+     */
+    drawables?: DrawableNode[];
+    /**
+     * World-to-pixel projector for `drawables`. When absent, `drawables` are ignored.
+     */
+    projector?: Projector;
     /**
      * Top-right status chip row (live measurements, scores, counters).
      * @synonyms chips, stats, measurements
@@ -4041,7 +4091,11 @@ interface BreadcrumbProps {
      * `{ label, href, index }` — the trait handles it with
      * `(navigate ?href)`. Without it, stack crumbs navigate directly.
      */
-    itemEvent?: EventKey;
+    itemEvent?: EventEmit<{
+        label: string;
+        href?: string;
+        index: number;
+    }>;
     /**
      * Separator icon (canonical kebab-case name or LucideIcon component)
      */
@@ -4125,9 +4179,17 @@ interface FilterGroupProps {
     /** Layer 2 visual treatment — orthogonal to the semantic variant. */
     look?: FilterGroupLook;
     /** Declarative filter event — emits UI:{event} via eventBus on filter change (alongside canonical UI:FILTER) */
-    event?: EventKey;
+    event?: EventEmit<{
+        entity: string;
+        field: string;
+        value: string;
+        query?: string;
+    }>;
     /** Declarative clear event — emits UI:{clearEvent} via eventBus on clear-all (alongside canonical UI:CLEAR_FILTERS) */
-    clearEvent?: EventKey;
+    clearEvent?: EventEmit<{
+        entity: string;
+        query?: string;
+    }>;
 }
 declare const FilterGroup: React__default.FC<FilterGroupProps>;
 
@@ -4245,7 +4307,9 @@ interface CardProps {
     maxLevel?: number;
     /** Event emitted on long press: UI:{longPressEvent} (payload: longPressPayload spread — variable) */
     longPressEvent?: EventEmit<EventPayload>;
-    /** Additional payload for long-press events */
+    /** Additional payload for long-press events
+     *  @payloadFor longPressEvent
+     */
     longPressPayload?: EventPayload;
 }
 /**
@@ -4375,6 +4439,7 @@ interface FloatingActionButtonProps {
     action?: EventKey;
     /**
      * Payload to include with the dispatched action event.
+     *  @payloadFor action
      */
     actionPayload?: EventPayload;
     /**
@@ -4919,7 +4984,10 @@ interface SearchInputProps extends Omit<React__default.InputHTMLAttributes<HTMLI
      */
     className?: string;
     /** Declarative search event — emits UI:{event} via eventBus on query submit (alongside canonical UI:SEARCH) */
-    event?: EventKey;
+    event?: EventEmit<{
+        searchTerm: string;
+        entity?: string;
+    }>;
     /**
      * Entity type for context-aware search.
      * When provided, search events include entity context.
@@ -5516,7 +5584,8 @@ interface CalendarGridProps {
     onSlotClick?: (day: Date, time: string) => void;
     /** Called when a day header is clicked */
     onDayClick?: (day: Date) => void;
-    /** Called when an event is clicked */
+    /** Called when an event is clicked
+     *  @entityRow event */
     onEventClick?: (event: EntityRow) => void;
     /** Additional CSS classes */
     className?: string;
@@ -5525,7 +5594,9 @@ interface CalendarGridProps {
         date: string;
         time?: string;
     }>;
-    /** Additional payload for long-press events */
+    /** Additional payload for long-press events
+     *  @payloadFor longPressEvent
+     */
     longPressPayload?: EventPayload;
     /** Event emitted on swipe left (next week): UI:{swipeLeftEvent} */
     swipeLeftEvent?: EventEmit<Record<string, never>>;
@@ -5852,7 +5923,7 @@ interface EmojiPickerProps {
     /**
      * Declarative event name — picking an emoji emits UI:{pickEvent} with { emoji } via eventBus
      */
-    pickEvent?: EventKey;
+    pickEvent?: EventEmit<EmojiPickPayload>;
     /**
      * Which side of the trigger the panel opens on
      * @default 'top'
@@ -6191,6 +6262,12 @@ interface MathCanvasProps {
     hops?: MathHop[];
     /** Extra declarative shapes in canvas pixel coordinates. */
     shapes?: LearningShape[];
+    /**
+     * Game-canvas drawables painted in math world coordinates (e.g. `draw-sprite`
+     * for a character sprite on the graph). The canvas maps their `ScenePos` through
+     * the same x/y world→pixel transform used for curves/points.
+     */
+    drawables?: DrawableNode[];
     /** Top-right status chips, forwarded verbatim to LearningCanvas. */
     readouts?: LearningReadout[];
     /** Inset sparkline panels, forwarded verbatim to LearningCanvas. */
@@ -7351,8 +7428,12 @@ interface NumberStepperProps {
     /** Direct onChange callback */
     onChange?: (value: number) => void;
     /** Declarative event name for value changes */
-    action?: EventKey;
-    /** Payload to include with the action event */
+    action?: EventEmit<{
+        value: number;
+    }>;
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Additional CSS classes */
     className?: string;
@@ -7375,8 +7456,12 @@ interface StarRatingProps {
     /** Star size */
     size?: StarRatingSize;
     /** Declarative event name for rating changes */
-    action?: EventKey;
-    /** Payload to include with the action event */
+    action?: EventEmit<{
+        value: number;
+    }>;
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Direct onChange callback */
     onChange?: (value: number) => void;
@@ -7403,8 +7488,17 @@ interface UploadDropZoneProps {
     /** Disabled state */
     disabled?: boolean;
     /** Declarative event name for file selection */
-    action?: EventKey;
-    /** Payload to include with the action event */
+    action?: EventEmit<{
+        files: {
+            name: string;
+            size: number;
+            type: string;
+            content: string;
+        }[];
+    }>;
+    /** Payload to include with the action event
+     *  @payloadFor action
+     */
     actionPayload?: EventPayload;
     /** Direct onFiles callback */
     onFiles?: (files: File[]) => void;
@@ -7577,7 +7671,7 @@ interface DataGridProps extends DataDndProps {
     /** Enable multi-select with checkboxes */
     selectable?: boolean;
     /** Selection change event name (emits UI:{selectionEvent} with { selectedIds: string[] }) */
-    selectionEvent?: EventKey;
+    selectionEvent?: EventEmit<SelectionChangePayload>;
     /** Enable infinite scroll loading */
     infiniteScroll?: boolean;
     /** Event emitted when more items needed: UI:{loadMoreEvent} */
@@ -7603,7 +7697,7 @@ interface DataGridProps extends DataDndProps {
      */
     look?: "dense" | "spacious" | "striped" | "borderless" | "card-rows";
 }
-declare function DataGrid({ entity, fields, columns, itemActions, maxInlineActions, scrollX, cols, gap, minCardWidth, className, isLoading, error, imageField, selectable, selectionEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, renderItem: schemaRenderItem, dragGroup, accepts, sortable, dropEvent, reorderEvent, positionEvent, dndItemIdField, dndRoot, look, }: DataGridProps): string | number | bigint | boolean | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | React__default.JSX.Element | null | undefined;
+declare function DataGrid({ entity, fields, columns, itemActions, maxInlineActions, scrollX, cols, gap, minCardWidth, className, isLoading, error, imageField, selectable, selectionEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, renderItem: schemaRenderItem, dragGroup, accepts, sortable, dropEvent, reorderEvent, positionEvent, dndItemIdField, dndRoot, look, }: DataGridProps): string | number | bigint | boolean | React__default.JSX.Element | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | null | undefined;
 declare namespace DataGrid {
     var displayName: string;
 }
@@ -7673,7 +7767,8 @@ interface DataListProps extends DataDndProps {
     maxInlineActions?: number;
     /** When set, the whole row is clickable and emits UI:{itemClickEvent} with
      *  { id, row } (action-button clicks stopPropagation so they still win). */
-    itemClickEvent?: EventKey;
+    /** @entityRow row */
+    itemClickEvent?: EventEmit<ItemActionPayload>;
     /** Gap between rows */
     gap?: 'none' | 'sm' | 'md' | 'lg';
     /** Visual variant */
@@ -7756,7 +7851,7 @@ interface DataListProps extends DataDndProps {
      */
     look?: "dense" | "spacious" | "striped" | "borderless" | "card-rows";
 }
-declare function DataList({ entity, fields, columns, itemActions, maxInlineActions, itemClickEvent, gap, variant, groupBy, senderField, senderLabelField, currentUser, emptyMessage, className, isLoading, error, reorderable: _reorderable, reorderEvent: _reorderEvent, swipeLeftEvent: _swipeLeftEvent, swipeLeftActions: _swipeLeftActions, swipeRightEvent: _swipeRightEvent, swipeRightActions: _swipeRightActions, longPressEvent: _longPressEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, sortBy, sortDirection, renderItem: schemaRenderItem, dragGroup, accepts, sortable: sortableProp, dropEvent, reorderEvent: dndReorderEvent, positionEvent, dndItemIdField, dndRoot, look, }: DataListProps): string | number | bigint | boolean | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | React__default.JSX.Element | null | undefined;
+declare function DataList({ entity, fields, columns, itemActions, maxInlineActions, itemClickEvent, gap, variant, groupBy, senderField, senderLabelField, currentUser, emptyMessage, className, isLoading, error, reorderable: _reorderable, reorderEvent: _reorderEvent, swipeLeftEvent: _swipeLeftEvent, swipeLeftActions: _swipeLeftActions, swipeRightEvent: _swipeRightEvent, swipeRightActions: _swipeRightActions, longPressEvent: _longPressEvent, infiniteScroll, loadMoreEvent, hasMore, children, pageSize, sortBy, sortDirection, renderItem: schemaRenderItem, dragGroup, accepts, sortable: sortableProp, dropEvent, reorderEvent: dndReorderEvent, positionEvent, dndItemIdField, dndRoot, look, }: DataListProps): string | number | bigint | boolean | React__default.JSX.Element | Iterable<React__default.ReactNode> | Promise<string | number | bigint | boolean | React__default.ReactPortal | React__default.ReactElement<unknown, string | React__default.JSXElementConstructor<any>> | Iterable<React__default.ReactNode> | null | undefined> | null | undefined;
 declare namespace DataList {
     var displayName: string;
 }
@@ -7837,12 +7932,15 @@ interface TableViewProps extends DataDndProps {
     itemClickEvent?: EventKey;
     /** Render a leading checkbox column. Selection changes emit `selectEvent`. */
     selectable?: boolean;
-    /** Event emitted on selection change: UI:{selectEvent} with { ids, rows }. */
-    selectEvent?: EventKey;
+    /** Event emitted on selection change: UI:{selectEvent} with { selectedIds }. */
+    selectEvent?: EventEmit<SelectionChangePayload>;
     /** Currently-selected ids (controlled). Falls back to local state when omitted. */
     selectedIds?: readonly string[];
     /** Event emitted on sortable-header click: UI:{sortEvent} with { column, direction }. */
-    sortEvent?: EventKey;
+    sortEvent?: EventEmit<{
+        column: string;
+        direction: 'asc' | 'desc';
+    }>;
     /** Current sort column (display hint for the active header arrow). */
     sortColumn?: string;
     /** Current sort direction (display hint). */
@@ -8033,7 +8131,13 @@ interface SortableListProps {
     items: readonly EntityRow[];
     /** Render function for each item. In .lolo: renderItem: (fn item <Component …={@item.field}/>), binding per-item fields via @item.field. */
     renderItem: (item: EntityRow, index: number) => React__default.ReactNode;
-    reorderEvent: EventKey;
+    /** @entityRow item */
+    reorderEvent: EventEmit<{
+        fromIndex: number;
+        toIndex: number;
+        item: EntityRow;
+    }>;
+    /** @payloadFor reorderEvent */
     reorderPayload?: EventPayload;
     dragHandlePosition?: 'left' | 'right';
     className?: string;
@@ -8076,7 +8180,9 @@ interface CarouselProps<T = CarouselItem> {
     slideChangeEvent?: EventEmit<{
         index: number;
     }>;
-    /** Payload to include with the slide change event */
+    /** Payload to include with the slide change event
+     *  @payloadFor slideChangeEvent
+     */
     slideChangePayload?: JsonObject;
     /** Additional CSS classes */
     className?: string;
@@ -8094,7 +8200,9 @@ declare const Carousel: <T = CarouselItem>({ items, renderItem, children, autoPl
 interface PullToRefreshProps {
     /** Event name to emit on refresh (emitted as UI:{refreshEvent}) */
     refreshEvent: EventKey;
-    /** Payload to include with the refresh event */
+    /** Payload to include with the refresh event
+     *  @payloadFor refreshEvent
+     */
     refreshPayload?: EventPayload;
     /** Pull distance threshold to trigger refresh in px (default: 60) */
     threshold?: number;
@@ -8483,10 +8591,17 @@ interface TagInputProps {
     className?: string;
     /** Event emitted when a tag is added: `UI:{addEvent}` with payload
      *  `{ tag: string, value: string[] }`. */
-    addEvent?: EventKey;
+    addEvent?: EventEmit<{
+        tag: string;
+        value: string[];
+    }>;
     /** Event emitted when a tag is removed: `UI:{removeEvent}` with
      *  payload `{ tag: string, index: number, value: string[] }`. */
-    removeEvent?: EventKey;
+    removeEvent?: EventEmit<{
+        tag: string;
+        index: number;
+        value: string[];
+    }>;
 }
 declare const TagInput: React__default.FC<TagInputProps>;
 
@@ -9916,38 +10031,38 @@ interface WizardField {
         label: string;
         isDefault?: boolean;
     }>;
-    defaultValue?: JsonValue;
-    condition?: JsonValue[];
+    defaultValue?: ControlValue;
+    condition?: SExpr;
     placeholder?: string;
     entityField?: string;
     minLength?: number;
     maxLength?: number;
-    dataSource?: JsonObject;
+    dataSource?: Record<string, FieldValue>;
     displayFields?: string[];
-    searchConfig?: JsonObject;
+    searchConfig?: Record<string, FieldValue>;
     hiddenCalculations?: Array<{
         variable: string;
         expression: string;
         scope?: string;
     }>;
-    signatureConfig?: JsonObject;
-    displayTemplate?: JsonObject;
-    lawReference?: JsonObject;
+    signatureConfig?: Record<string, FieldValue>;
+    displayTemplate?: Record<string, FieldValue>;
+    lawReference?: Record<string, FieldValue>;
     contextMenu?: string[];
-    calculated?: JsonObject;
+    calculated?: Record<string, FieldValue>;
     readOnly?: boolean;
-    minDate?: JsonValue;
+    minDate?: string;
     stats?: Array<{
         label: string;
-        value: JsonValue;
+        value: ControlValue;
         icon?: string;
     }>;
     items?: Array<{
         id: string;
         label: string;
-        autoCheck?: JsonValue;
+        autoCheck?: boolean;
     }>;
-    [key: string]: JsonValue | undefined;
+    [key: string]: JsonValue | SExpr | ControlValue | Record<string, FieldValue> | undefined;
 }
 /** Section within a wizard step */
 interface WizardSection {
@@ -9956,7 +10071,7 @@ interface WizardSection {
     description?: string;
     fields?: WizardField[];
     subsections?: WizardSection[];
-    condition?: JsonValue[];
+    condition?: SExpr;
     repeatable?: boolean;
     minItems?: number;
     addButtonLabel?: string;
@@ -9965,9 +10080,9 @@ interface WizardSection {
         expression: string;
         scope?: string;
     }>;
-    dataSource?: JsonObject;
+    dataSource?: Record<string, FieldValue>;
     readOnly?: boolean;
-    [key: string]: JsonValue | WizardField[] | WizardSection[] | undefined;
+    [key: string]: JsonValue | SExpr | Record<string, FieldValue> | WizardField[] | WizardSection[] | undefined;
 }
 /** Entity mapping configuration */
 interface WizardEntityMapping {
@@ -9979,7 +10094,7 @@ interface WizardEntityMapping {
 }
 /** Validation rule for wizard steps */
 interface WizardValidationRule {
-    condition: JsonValue[];
+    condition: SExpr;
     message: string;
 }
 /** Law reference for compliance */
@@ -10048,9 +10163,13 @@ interface WizardContainerProps {
     /** Error state */
     error?: UiError | null;
     /** Emits UI:{nextEvent} when advancing to next step */
-    nextEvent?: EventKey;
+    nextEvent?: EventEmit<{
+        step: number;
+    }>;
     /** Emits UI:{backEvent} when going to previous step */
-    backEvent?: EventKey;
+    backEvent?: EventEmit<{
+        step: number;
+    }>;
     /** Emits UI:{completeEvent} when wizard completes */
     completeEvent?: EventKey;
 }
@@ -11220,8 +11339,12 @@ interface FormProps extends Omit<React__default.FormHTMLAttributes<HTMLFormEleme
     showSubmit?: boolean;
     /** Form title (used by ModalSlot to extract title) */
     title?: string;
-    /** Event to dispatch on successful submit (defaults to 'SAVE') */
-    submitEvent?: EventKey;
+    /** Event to dispatch on successful submit (defaults to 'SAVE').
+     *  `data` carries the collected field values for the bound entity, so it is
+     *  the bound entity's ROW — a compile-time-known type via `linkedEntity`,
+     *  unlike the per-field `value` whose type depends on a runtime `fieldId`. */
+    /** @entityRow data */
+    submitEvent?: EventEmit<FormSubmitPayload>;
     /** Event to dispatch on cancel (defaults to 'CANCEL') */
     cancelEvent?: EventKey;
     /** Data for relation fields: { fieldName: RelationOption[] } */
@@ -11244,7 +11367,7 @@ interface FormProps extends Omit<React__default.FormHTMLAttributes<HTMLFormEleme
     /** Callback when any field value changes */
     onFieldChange?: (change: {
         fieldId: string;
-        value: FieldValue | undefined;
+        value: ControlValue | undefined;
         formValues: Record<string, FieldValue | undefined>;
     }) => void;
     /** Config path for form configuration (schema-driven) */
@@ -12609,8 +12732,18 @@ interface TopBarAction {
     /** Bus event fired on click. Dispatched as `UI:{event}` with empty payload.
      *  Typed as `EventKey` so the pattern-sync detector marks `topBarActions`
      *  as `event-list` and the validator checks references against trait
-     *  emit/listen sets. */
-    event: EventKey;
+     *  emit/listen sets.
+     *
+     *  Optional because an action may navigate instead of dispatching — see
+     *  `navigatesTo`. At least one of the two should be set; an entry with
+     *  neither renders an inert button. */
+    event?: EventKey;
+    /** Destination URL. Emits `UI:NAVIGATE` on click, the same mechanism
+     *  `ButtonGroup` / `PageHeader` / `DocumentViewer` already use for their
+     *  action descriptors — the top bar was the odd one out, which forced a
+     *  navigation-only button to invent an event nothing listens for. Set
+     *  alongside `event` to both dispatch and navigate. */
+    navigatesTo?: string;
     /** Optional badge — number or string rendered in the corner of the icon. */
     badge?: number | string;
     /** Visual variant. Default `"default"`. */