@almadar/ui 5.166.0 → 6.1.0

package/dist/components/index.d.cts

@@ -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, JsonObject, EntityRow, FieldValue, EntityRole, AnimationName, SpriteDirection, AnimationDef, ScenePos, Camera, EntityWith, TraitConfigValue, JsonValue, AssetCatalog, EventPayloadValue, DeclaredTraitConfig, TraitConfig, OrbitalSchema, Trait, OrbitalEntity, FormSubmitPayload, ControlValue, 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.cjs';
 export { R as Rect } from '../types-B3nHgnMG.cjs';
 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-Do_LPV1o.cjs';
-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-Do_LPV1o.cjs';
-import { D as DrawableNode, F as FxOverlayItem, M as MeshShapeKind, a as MeshMaterial, b as DrawGroupProps, c as DrawTextProps, d as DrawMeshProps } from '../paintDispatch-DgBctxIq.cjs';
-export { e as FxOverlayKind } from '../paintDispatch-DgBctxIq.cjs';
+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-C6Yz2MuW.cjs';
+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-C6Yz2MuW.cjs';
+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-D3R8NNmV.cjs';
+export { e as FxOverlayKind } from '../paintDispatch-D3R8NNmV.cjs';
 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-CQAdPreB.cjs';
-import { C as ContentSegment, L as LessonSegment, U as InteractiveOrbitalType, b as DomLayoutData, d as DomStateNode, V as VisualizerConfig, e as DomTransitionLabel } from '../cn-TH-RHihd.cjs';
-export { W as BloomLevel, X as BloomQuizBlock, Y as BloomQuizBlockProps, Z as MixedSegment, n as cn, A as parseLessonSegments, _ as parseMarkdownWithCodeBlocks } from '../cn-TH-RHihd.cjs';
+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-DJSBBm5W.cjs';
+export { W as BloomLevel, X as BloomQuizBlock, Y as BloomQuizBlockProps, Z as MixedSegment, n as cn, A as parseLessonSegments, _ as parseMarkdownWithCodeBlocks } from '../cn-DJSBBm5W.cjs';
 import { b as SlotContent, d as SlotPropValue } from '../useUISlots-GNwGLlW2.cjs';
 export { D as DEFAULT_SLOTS, S as SlotAnimation, a as SlotChangeCallback, c as SlotRenderConfig, U as UISlotManager, u as useUISlotManager } from '../useUISlots-GNwGLlW2.cjs';
 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.cjs';
@@ -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;
+    }>;
     /**
      * 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
@@ -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 */
@@ -2422,6 +2460,10 @@ declare namespace GameMenu {
 interface StateGraphTransition {
     from: string;
     to: string;
+    /** Deliberately NOT `EventKey`: this is a drawn arrow's caption, not a bus
+     *  event. Typing it `EventKey` would tag `transitions` as an `event-list`
+     *  and validate the PLAYER's invented state-machine vocabulary against the
+     *  orbital's event set. The real bus outlet here is `nodeClickEvent`. */
     event: string;
     guardHint?: string;
 }
@@ -2443,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;
@@ -3375,6 +3419,10 @@ declare namespace TransitionArrow {
 interface StateJsonTransition {
     from: string;
     to: string;
+    /** Deliberately NOT `EventKey`: these are JSON.stringify'd into a code
+     *  block for display. This component has no event bus and cannot emit;
+     *  tagging `transitions` as an `event-list` would police the PLAYER's
+     *  invented vocabulary against the orbital's event set. */
     event: string;
 }
 interface StateJsonViewProps {
@@ -3478,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;
@@ -3596,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
@@ -4033,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)
      */
@@ -4117,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>;
 
@@ -4237,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;
 }
 /**
@@ -4367,6 +4439,7 @@ interface FloatingActionButtonProps {
     action?: EventKey;
     /**
      * Payload to include with the dispatched action event.
+     *  @payloadFor action
      */
     actionPayload?: EventPayload;
     /**
@@ -4911,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.
@@ -5508,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;
@@ -5517,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>>;
@@ -5844,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'
@@ -6183,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. */
@@ -7343,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;
@@ -7367,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;
@@ -7395,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;
@@ -7569,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} */
@@ -7665,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 */
@@ -7829,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). */
@@ -8025,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;
@@ -8068,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;
@@ -8086,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;
@@ -8475,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>;
 
@@ -10040,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;
 }
@@ -11212,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[] } */
@@ -11236,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) */
@@ -12601,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"`. */